








x Commodore! D 8 
c Commodore! PED) 


System Guide 








C= Commodore == 


System Guide 
Commodore 


128 
IZ8D 


Personal Computer 


© Commodore Electronics, Ltd. 1985. All rights reserved. 


Please note: All information about the C 128 
in this manual is also valid for the C 128 D 


Copyright © 1985 by Commodore Electronics Limited 
All rights reserved 


This manual contains copyrighted and proprietary information. No part of this publication may 
be reproduced, stored in a retrieval system, or transmitted in any form or by any means, 
electronic, mechanical, photocopying, recording or otherwise, without the prior written 
permission of Commodore Electronics Limited. 


Commodore BASIC 7.0 
Copyright © 1985 by Commodore Electronics Limited; All rights reserved 


Copyright © 1977 by Microsoft Corp. 
All rights reserved 


CP/M® Plus Version 3.0 


Copyright © 1982 Digital Research Inc. 
All rights reserved 


CP/M is a registered trademark of Digital Research Inc. 


CONTENTS 
C128 SYSTEM GUIDE 


CHAPTER | — INTRODUCTION 


SECTION 1 — HOW TO USE THIS GUIDE 
SECTION 2 — OVERVIEW OF THE COMMODORE 128 
PERSONAL COMPUTER 


CHAPTER II — USING C128 MODE 


SECTION 3 — GETTING STARTED IN BASIC 
SECTION 4 — ADVANCED BASIC PROGRAMMING 
SECTION 5 — SOME BASIC COMMANDS AND 
KEYBOARD OPERATIONS UNIQUE TO C128 
SECTION 6 — COLOR, ANIMATION AND 
SPRITE GRAPHICS 
SECTION 7 — SOUND AND MUSIC IN C128 MODE 
SECTION 8 — USING 80 COLUMNS 


CHAPTER IIl — USING C64 MODE 


SECTION 9 — USING BASIC IN C64 MODE 
SECTION 10 — STORING AND REUSING YOUR 
PROGRAMS IN C64 MODE 


CHAPTER IV — CP/M MODE 
SECTION 11 — INTRODUCTION TO CP/M 3.0 


SECTION 12 — FILES, DISKS AND DRIVES IN 
CP/M 3.0 

SECTION 13 — USING THE CONSOLE AND PRINTER 
IN CP/M 3.0 

SECTION 14 — SUMMARY OF MAJOR 
CP/M 3.0 COMMANDS 

SECTION 15 — COMMODORE ENHANCEMENTS TO 

CP/M 3.0 


CHAPTER V — BASIC 7.0 ENCYCLOPAEDIA 


SECTION 16 — INTRODUCTION 16-3 
SECTION 17 — BASIC COMMANDS AND 

STATEMENTS 17-3 
SECTION 18 — BASIC FUNCTIONS 18-3 
SECTION 19 — VARIABLES AND OPERATIONS 19-3 
SECTION 20 — RESERVED WORDS AND SYMBOLS 20-3 


APPENDICES 


APPENDIX 
APPENDIX 
APPENDIX 


APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 


GLOSSARY 


INDEX 


TACT TOMMO Qw,r 


BASIC LANGUAGE ERROR MESSAGES 
DOS ERROR MESSAGES 
CONNECTORS/PORTS FOR PERIPHERAL 
EQUIPMENT 

SCREEN DISPLAY CODES 

ASCII AND CHR$ CODES 

SCREEN AND COLOR MEMORY MAPS 
DERIVED MATHEMATICAL FUNCTIONS 
MEMORY MAP 

CONTROL AND ESCAPE CODES 
MACHINE LANGUAGE MONITOR 
BASIC 7.0 ABBREVIATIONS 

DISK COMMAND SUMMARY 


CHAPTER 





INTRODUCTION 


SECTION 1 
How to Use This Guide 


This Commodore 128 System Guide is designed to help you 
make full use of the advanced capabilities of the Commodore 
128 computer. 


Before you read any further in this System Guide, make 
sure you have read the other book that comes with your 
computer, the Commodore 128 Personal Computer 
Introductory Guide. This introductory guide contains 


important information on getting started with the Commodore 


128. 


If you are primarily interested in using the BASIC language 
to create and run your own programs, you should read 


Chapter Il, USING C128 MODE. This chapter introduces you 


to the BASIC programming language as used in both C128 
and C64 modes, describes the Commodore 128 keyboard, 
defines some advanced commands you Can use in both 
C128 and C64 modes, shows how to use a number of 

powerful new BASIC commands (including colour, graphic 
and sound commands) that are unique to C128 Mode, and 


describes how to use the 80-column capabilities available in 


C128 Mode. 


If you want to use BASIC in C64 Mode, read Chapter Ill, 
USING C64 MODE. 


If you want to use CP/M on the Commodore 128, read 


Chapter IV, USING CP/M MODE. This chapter tells you how 
to start up and use CP/M on the Commodore 128. In CP/M 


you can choose from thousands of commercial software 
packages, including the PERFECT series (PERFECT 

WRITER, PERFECT CALC, PERFECT FILER). You can also 
create your own CP/M programs. 


If you want details on the BASIC 7.0 commands, read 


Chapter V, BASIC 7.0 ENCYCLOPAEDIA. This chapter gives 


format and usage details on all BASIC 7.0 commands, 
statements and functions. 


If, after reading Chapters | through V, you are looking for 
additional technical information about a particular 
Commodore 128 topic, first check the Appendices to this 


System Guide. These appendices contain a wide range of 
information, such as a complete list of BASIC and DOS error 
messages and a summary of disk commands. A Glossary 
following the Appendices provides definitions of computing 


terms. 


For complete technical details about any feature of the 
Commodore 128, consult the Commodore 128 Programmer's 


Reference Guide. 


SECTION 2 


Overview of the Commodore 
C128 Personal Computer 


OVERVIEW OF THE COMMODORE C128 PERSONAL 
COMPUTER 
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OVERVIEW OF THE COMMODORE C128 PERSONAL 
COMPUTER 


The Commodore 128 Personal Computer offers three primary 
operating modes: 


* €128 Mode 
* C64 Mode 
* CP/M Mode 


C128 Mode 


In C128 Mode, the Commodore 128 Personal Computer provides 
access to 128K of RAM and a powerful extended BASIC 
language known as BASIC 7.0. BASIC 7.0 offers over 140 
commands, statements and functions. C128 Mode also provides 
both 40 and 80 column output and full use of the 92-key 
keyboard. A built-in machine language monitor allows you to 
create and debug your own machine language programs. In 
C128 Mode you can use a number of new peripheral devices 
from Commodore, including a new fast serial disk drive (the 
1571), a mouse, and a 40/80 column composite video/RGBI 
monitor (the 1901). You can also use all standard Commodore 
serial peripherals. 


C64 Mode 


In C64 Mode, the Commodore 128 operates exactly like a 
Commodore 64 computer, allowing you to take full advantage of 
the wide range of available C64 software. You also have full 
compatibility with all C64 peripherals. 


C64 Mode provides the BASIC 2.0 language, 40 column output 
and access to 64K of RAM. 


CP/M Mode 


In CP/M Mode, an onboard Z80 microprocessor gives you all the 
capabilities of Digital Research’s CP/M Plus version 3.0, plus 
several new capabilities added by Commodore. The Commodore 
128’s CP/M package, called CP/M Plus, provides 128K of RAM, 
40 and 80 column output, access to the full keyboard, including 
the numeric keypad and special keys, and access to the new 
Commodore 1571 fast serial disk drive as well as standard serial 
peripherals. 
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Chapters Il, Ill and IV, which include Sections 3 through 15, tell 
you how to access and use the capabilities of the three powerful 
and versatile operating modes of the Commodore 128 Personal 
Computer. 


Switching Between Modes 


The following chart tells you how to switch to one mode from 
another. 


NOTE: If you are using a Commodore 1901 dual monitor, 
remember to move the video switch on the monitor from 
COMPOSITE or SEPARATED to RGBI when switching from 40 
column to 80 column display. Reverse this step when switching 
from 80 to 40 columns. 
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TO 


C128 
40 COL 


C128 
80 COL 


C64 


CPIM 
40 COL 


CPIM 
80 COL 


OFF 


. Check that 


40/80 key is 
UP. 


. Turn computer 
ON. 


. Press 40/80 


key DOWN. 
Turn computer 
ON 


Hold ¢ key 
DOWN, 


Turn computer 
ON. 

OR 
Insert C64 
cartridge 


. Turn computer 
ON 


Turn disk drive 
ON 


Insert CP/M 
system disk in 
Crive 

Check that 
40/80 key Is 
UP 


. Turn computer 
ON 


. Turn disk drive 
ON 


insert CP/M 
system disk in 
drive 

Press 40/80 
key DOWN 


_ Jurn computer 
ON. 


le 


Le 


2 


3 


2 


3 


o 


MODE SWITCHING CHART 


C128 
40 COL 


Press ESE !.2y; 
release. 


Press X key. 
OR 


Press 40/80 
key DOWN. 
Press RESET 
button. 


Type GO 64: 1 
press RETURN. 


The computer 2. 


responds: 

ARE YOU SURE? 
Type Y: press 
RETURN. 


Turn disk drive 1. 


Insert CP/M 2. 


system disk in 
drive. 


Check that 3 
40/80 key is 

UP. 

Type: BOOT 4 


Press RETURN 5 


CPIM 
40 COL 


. Check that 


40/80 key is UP. 


. Turn computer 


OFF, then ON. 


. Press 40/80 key 


DOWN 


. Remove CP/M 


system disk from 
drive, if 
necessary. 


. Turn computer 


OFF. then ON. 


Turn computer 
OFF. 


. Check that 40/ 


80 key is UP 


. Hold DOWN & 


key while turning 
computer ON. 
OR 


. Turn computer 
OFF. 


. Insert C64 


cartridge. 


. Turn power ON. 








Turn disk drive 1. 
ON. 


Insert CP/M 2. 


system disk in 
drive 


Press 40/80 3. 


key DOWN 
Type: BOOT 


Press RETURN 4- 
5. 





FROM 
C128 C64 
80 COL 
. Press ESC key; 1. Check that 
release. 40/80 key is 
Press X key. UP. 
OR 2 Turn computer 
. Check that OFF, then ON. 
40/80 key is 
UP. 
. Press RESET 
button. 
1. Press 40/80" 
key DOWN. 
2. Turn computer 
OFF, then ON 
Type GO 64. 
press RETURN 
The computer 
responds: 
ARE YOU SURE? 
Type Y: press 
RETURN. 
Turn disk drive 1 Check that 
40/80 key is 
Insert CP/M UP. 
system diskin 2 Turn disk drive 
drive. ON. 
Check that 3. insert CP/M 
40/80 key is system disk in 
UP. drive. 
Type: BOOT 4 Turn computer 
Press RETURN —_—DFF. then ON 
Turn disk drive 1, Press 40/80 
ON key DOWN. 


Insert CP/M 2 
system disk in 


Turn disk drive 


drive. 3 Insert CP/M 
Check that system disk in 
40/80 key is drive, 

DOWN 4 Turn computer 
Type: BOOT OFF, then ON. 
Press RETURN 


. Insert CP/M 


utilities disk in 
drive. 

At screen 
prompt. A> type 
OEVICECONOUT = 80COL 


_ Press RETURN. 


Me 


q 


als 


CPIM 
80 COL 


Check that 
40/80 key is UP. 


. Turn computer 


OFF, then ON. 


. Check that 


40/80 key is 
DOWN. 


Remove CP/M 
system disk trom 
drive. if 
necessary. 

Turn computer 
OFF, then ON. 


Turn computer 
OFF. 
Check that 40/ 


80 key is UP 


Hold DOWN & 

key while turning 

computer ON. 
OR 


Turn computer 
OFF. 

Insert C64 
cartridge. 

Turn power ON. 


. insert CP/M 


utilities disk in 
drive. 

At Screen 
prompt, A> type: 
DEVICECONOUT: = 40COt 
Press RETURN. 


NOTE: If you are using a Commodore 1902 dual monitor, remember to move the video 
switch on the monitor trom COMPOSITE or SEPARATED to RGB! when switching from 


40-column to 80-column display; reverse this step when switching trom 80 to 40 
columns. Also, when switching between modes remove any cartridges from the 


expansion port and any disks from the disk drive. 
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BASIC PROGRAMMING LANGUAGE 


The BASIC programming language is a special language that lets 
you communicate with your Commodore 128. Using BASIC is 
one means by which you instruct your computer what to do. 


BASIC has its own vocabulary (made up of commands, 
statements and functions) and its own rules of structure (called 
syntax). You can use the BASIC vocabulary and syntax to create 
a set of instructions called a program, which your computer can 
then perform or “run.” 


Using BASIC, you can communicate with your Commodore 128 
in two ways: within a program, or directly (outside a program). 


Direct Mode 


Your Commodore 128 is ready to accept BASIC commands in 
direct mode as soon as you turn on the computer. In the direct 
mode, you type commands on the keyboard and enter them into 
the computer by pressing the RETURN key. The computer 
executes all direct mode commands immediately after you press 
the RETURN key. Most BASIC commands in your Commodore 
128 can be used in direct mode as well as in a program. 


Program Mode 


In program mode you enter a set of instructions that perform a 
specific task. Each instruction is contained in a sequential 
program line. A statement in a program may be as long as 160 
characters; this is equivalent to four full screen lines in 40- 
column format, and two full screen lines in 80-column format. 


Once you have typed a program, you can use it immediately by 
typing the RUN command and pressing the RETURN key. You 
can also store the program on disk or tape by using the DSAVE 
(or SAVE) command. Then you can recall it from the disk or tape 
by using the DLOAD (or LOAD) command. This command copies 
the program from the disk or tape and places that program in the 
Commodore 128’s memory. You can then use or “execute” the 
program again by entering the RUN command. All these 
commands are explained later in this section. Most of the time 
you will be using your computer with programs, including 
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programs you yourself write, and commercially available software 
packages. The only time you operate in direct mode is when you 
are manipulating or editing your programs with commands such 
as LIST, LOAD, SAVE and RUN. As a rule, the difference between 
direct mode and operation within a program is that direct mode 
commands have no line numbers. 


USING THE KEYBOARD 


Shown below is the keyboard of the Commodore 128 Personal 
Computer. 



































Using BASIC is essentially the same in both C64 and C128 
modes. Most of the keys, and many of the commands you will 
learn, can be used to program BASIC in either mode. The keys 
that are shaded in the diagram above can be used in C64 mode. 
In C128 mode you can use all of the keys on the keyboard. 
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Keyboard Character Sets 


The Commodore 128 keyboard offers two different sets of 
Characters: 


@ Upper-case letters and graphic characters 
@ Upper- and lower case letters 


In 80-column format, both character sets are available 
simultaneously. This gives you a total of 512 different characters 
that you can display on the screen. In 40 column format you can 
use only one character set at a time. 


When you turn on the Commodore 128 in 40-column format, the 
keyboard normally is using the upper-case/ graphic character 
set. This means that everything you type is in capital letters. To 
switch back and forth between the two character sets, press the 
SHIFT key and the & key (the COMMODORE key) at the same 
time. To practice using the two character sets turn on your 
computer and press several letters or graphic characters. Then 
press the SHIFT key and the € (Commodore) key. Notice how 
the screen changes to upper- and lower-case characters. Press 
SHIFT and € again to return to the upper-case and graphic 
Character set. 


Using the Command Keys 


COMMAND keys are keys that send messages to the computer. 
Some command keys (such as RETURN) are used by 
themselves. Other command keys (such as SHIFT, CTRL, & and 
RESTORE) are used with other keys. The use of each of the 
command keys Is explained below. The keys used in C128 mode 
are described in Section 5. 


Return 


When you press the RETURN key, what you have typed is sent to 
the Commodore 128 computer's memory. Pressing the RETURN 
key also moves the cursor (the small flashing rectangle that 
marks where the next character you type will appear) to the next 
line. 


At times you may misspell a command or type in something the 
computer does not understand. Then, when you press the 
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RETURN key, you probably will get a message like SYNTAX 
ERROR on the screen. This is called an “Error Message.’ 
Appendix A lists the error messages and tells how to correct the 
errors. 


NOTE: the examples given in this book, the following symbol 
indicates that you must press the RETURN key: 


RETURN | 
Shift 


There are two SHIFT keys on the bottom row of the keyboard. 
One key is on the left and the other is on the right, just as on a 
standard typewriter keyboard. 


The SHIFT key can be used in three ways: 


1. With the upper/lower-case character set, the SHIFT key is 
used like the shift key on a regular typewriter. When the SHIFT 
key is held down, it lets you print capital letters or the top 
Characters on double-character keys. 


2. The SHIFT key can be used with some of the other command 
keys to perform special functions. 


3. When the keyboard is set for the upper-case/graphic 
Character set, you can use the SHIFT key to print the graphic 
symbols or characters that appear on the right of the front face 
of certain keys. See the paragraphs entitled “Displaying 
Graphic Characters” at the end of this section for more details. 


Shift Lock 


When you press this key down, it locks into place. Then, whatever 
you type will either be a capital letter, or the top character of a 
double-character key. To release the lock, press down on the 
SHIFT LOCK key again. 


Moving the Cursor 


In C128 mode, you can move the cursor by using either the four 
arrow keys located just above the top right of the main keyboard, 
or the two keys labeled CRSR, at the right of the bottom row of 
the main keyboard. 
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Using the Four Arrow Cursor Keys 


In C128 mode, the cursor can be moved in any direction simply 
by using the arrow key in the top row that points in the direction 
you want to move the cursor. (These keys cannot be used in C64 
mode). 


Using the CRSR keys 


In both C128 and C64 mode, you can use the two keys on the 
right side of the bottom row of the main keyboard to move the 
cursor: 


@ Pressing the vee key alone moves the cursor down. 


@ Pressing the csr and SHIFT keys together moves the cursor 
up. 


~—— 
@ Pressing the CRSR key alone moves the cursor right. 


~—= 
@ Pressing the CRSR and SHIFT keys together moves the cursor 
left. 


You don't have to keep tapping a cursor key to move more than 
one space. Just hold the key down and the cursor continues to 
move, release it when it reaches the position you want. 


Notice that when the cursor reaches the right side of the screen, 
it ‘wraps’, or Starts again at the beginning of the next row. When 
moving left, the cursor will move along the line until it reaches the 
edge of the screen, then it will jump up to the end of the 
preceding line. 


You should try to become very familiar with the cursor keys, 
because moving the cursor makes your programming much 
easier. With a little practice you will find that you can move the 
cursor almost without thinking about it. 


Inst/Del 


This is a dual purpose key. INST stands for INSerT, and DEL for 
DELete. 
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Inserting Characters 


You must use the SHIFT key with the INST/DEL key when you 
want to insert characters in a line. Suppose you left some 
Characters out of a line, like this: 


WHILE@® WERE OUT 


To insert the missing characters, first use the cursor keys to 
move the cursor back to the error, like this: 


WHILE@ WERE OUT 


Then, while you hold down the SHIFT key, press the INST/DEL 
key until you have enough space to add the missing characters: 


WHILE® U WERE OUT 


Notice that INST doesn’t move the cursor; it just adds space 
between the cursor and the character to its right. To make the 
correction, simply type in the missing “Y" and “O”, like this: 


WHILE YOU WERE OUT 


Deleting Characters 


When you press the DEL key, the cursor moves one space to the 
left and erases the character that is there and moves any 
characters to the right of the cursor one position to the left. This 
means that when you want to delete something, you move the 
cursor just to the right of the character you want to DELete. 
Suppose you have made a mistake in typing, like this: 


PRINT “ERROER” 


You wanted to type the word ERROR, not ERROER. To delete the 
incorrect E that precedes the final R, position the cursor on the 
final R. When you press the DEL key, the R automatically moves 
over one space to the left. You now have the correct wording like 
this: 


PRINT “ERROR” 


Using INSerT and DELete Together 


You can use the INSerT and DELete functions together to fix 
incorrect characters. First, move the cursor to the incorrect 
characters and press the INST/DEL key by itself to delete the 
characters. Next, press the SHIFT key and the INST/DEL key 
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together to add any necessary space. Then type in the 
corrections. You can also type directly on top of undesired 
characters, then use INST to add any needed space. 


Control 


The Control key is used with other keys to do special tasks called 
control functions. To perform a control function, hold down the 
Control key while you press some other key. A full list of control 
sequences is given in Appendix |. Control functions are often 
used in prepackaged software such as a word processing 
system. 


One control function that is used often is setting the character 
and cursor color. To select a color, hold down the CTRL key 
while you press a number key (1 through 8), on the top row of the 
keyboard. There are eight more colors available to you; these can 
be selected with the & key, as explained later. 


Run/Stop 


This is a dual function key. Under certain conditions you can use 
the RUN function of this key by pressing the SHIFT and 
RUN/STOP together. It is also possible to use the STOP function 
of this key to halt a program or a printout by pressing this key 
while the program is running. However, in most prepackaged 
programs, the STOP function of the RUN/STOP key is 
intentionally disabled (made unusable). This is done to prevent 
the user from trying to stop a program that is running before it 
reaches its normal end point. If the user were able to stop the 
program, valuable data could be lost. 


Restore 


The RESTORE key is used with the RUN/STOP key to return the 
computer to its standard condition. 


Most prepackaged programs disable the RESTORE key for the 
same reason they disable the STOP function of the RUN/STOP 
key: to prevent losing valuable data. 

CLR/Home 


CLR stands for CLeaR. HOME refers to the upper-left corner of 
the screen, which is called the HOME position. If you press this 


3-9 


key by itself the cursor returns to the HOME position. When you 
use the SHIFT key with the CLR/HOME key, the screen CLeaRs 
and the cursor returns to the HOME position. 


Commodore Key 


The & key (known as the COMMODORE key) has a number of 
functions, including the following ones: 


1. When used with the SHIFT key, the @ key lets you switch 
between upper-case/graphics mode and upper/lower-case 
text modes. 

2. When you're in either mode, the @ key acts as a shift to let you 
type the graphics symbol pictured on the LEFT front of each 
key. Just hold down @ and press the graphic key you want. 

3. When you want to change the color you are typing in to one of 
the 8 colors listed on the BOTTOM row of the face of the color 
keys, press @ and the color key you want. 

4, When you want to slow down a scrolling program display, hold 
down the & key. The display scrolling speed slows down 
considerably. When you release the key, the screen scrolling 
resumes normal speed. 

5. If you hold down the & key while turning on the computer, you 
can immediately access C64 mode. 


Function Keys 


The four keys located above the numeric keypad (marked F1, F3, 
F5 and F7 on the top and F2, F4, F6 and F8 on the front) are 
called function keys. In both C128 and C64 modes, you can 
program the function keys. (See the KEY command descriptions 
in Section 5 of Chapter Il and in Chapter V, BASIC 7.0 
ENCYCLOPAEDIA). These keys are also often used by 
prepackaged software to allow you to perform a task with a single 
keystroke. 


Displaying Graphic Characters 


To display the graphic symbol on the right front face of a key, 
hold down the SHIFT key while you press the key that has the 
graphic character you want to print. You can display the right 
side graphic characters only when the keyboard Is in the upper- 
case/graphics character set (one normal character set usually 
available at power-up). 
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To display the graphic character on the left front face of a key, 
hold down the & key while you press the key that has the 
graphic character you want. You can display the left graphic 
Character while the keyboard is in either character set. 


Rules for Typing BASIC Language Programs 


You can type and use BASIC language programs even without 
knowing BASIC. You must type carefully, however, because a 
typing error may cause the computer to reject your information. 
The following guidelines will help minimize errors when typing or 
copying a program listing. 


1. Spacing between words is not critical; e.g., typing 
FORT=1TO10 is the same as typing FORT=1 TO 10. 
However, a BASIC keyword itself must not be broken up by 
spaces. (See the BASIC 7.0 Encyclopaedia in Chapter V for a 
list of BASIC keywords). 


2. Any characters can be typed inside quotation marks. Some 
Characters have special functions when placed inside 
quotation marks. These functions are explained later in this 
Guide. 


3. Be careful with punctuation marks. Commas, colons and 
semicolons also have special properties, explained later in this 
section. 


4. Always press the RETURN key (indicated in this Guide by 
=RETFERIE ) after completing a numbered line. 


5. Never type more than 160 characters in a program line. 
Remember, this is the same as four full screen lines in 40- 
column format, or two full screen lines in 80-column format. 
See Section 8 for more details on 40- and 80-column formats. 





6. Distinguish clearly between the letter | and the numeral 1 and 
between the letter O and the numeral 0 


7. The computer ignores anything following the letters REM on a 
program line. REM stands for REMark. You can use the REM 
statement to put comments in your program that tell anyone 
listing the program what is happening at a specific point. 


Follow these guidelines when you type the examples and 
programs shown in this section. 
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GETTING STARTED — THE PRINT COMMAND 


The PRINT command tells the computer to display information on 
the screen. You can print both numbers and text (letters), but 
there are special rules for each case, described in the following 
paragraphs. 


Printing Numbers 


To print numbers, use the PRINT command followed by the 
number(s) you want to print. Try typing this on your Commodore 
126; 


PRINT 5 


Then press the RETURN key. Notice the number 5 is now 
displayed on the screen. 


Now type this and press RETURN: 
PRINT 5,6 


In this PRINT command, the comma tells the Commodore 128 
that you want to print more than one number. When the computer 
finds commas in a string of numbers in a PRINT statement, the 
output is displayed to the nearest tenth column. If you don't want 
all the extra spaces, use a semicolon (;) in your PRINT statement 
instead of acomma. The semicolon tells the computer to print the 
numbers next to each other. A number when printed has either a 
space or a minus sign preceding It and a skip character after it. 
Type these examples and see what happens: 


PRINT 5:6 RETURN 
PRINT 100;-200;300;-400;500 SETHRM 


Using the Question Mark to Abbreviate the PRINT Command 


You can use a question mark (?) as an abbreviation for the 
PRINT command. Many of the examples in this section use the ? 
symbol in place of the word PRINT. In fact, most of the BASIC 
commands can be abbreviated. The abbreviations for BASIC 
commands can be found in Appendix K of this Guide. 


Printing Text 


Now that you know how to print numbers, it’s time to learn how to 
print text. It's actually very simple. Any words or characters you 
want to display are typed on the screen, with a quote symbol at 
each end of the string of characters. String is the BASIC name 
for any set of characters surrounded by quotes. The quote 
Character is obtained by pressing SHIFT and the numeral 2 key 
on the top row of the keyboard (not the 2 in the numeric keypad). 
Try these examples: 


? “COMMODORE 128” =i 
2 “4*5” SRETORRE 


Notice that when you press RETURN, the computer displays the 
characters within the quotes on the screen. Also note that the 
second example did not calculate 4*5 since it was treated as a 
string and not a mathematical calculation. If you want to calculate 
the result 4*5, use the following command: 


? 4*5 RETURN 


You can PRINT any string you want by using the PRINT 
command and surrounding the printed characters with quotes. 
You can combine text and calculations in a single PRINT 
command like this: 





See how the computer PRINTs the characters in quotes, makes 
the calculation and PRINTs the result. It doesn’t matter whether 
the text or calculation comes first. In fact, you can use both 
several times in one PRINT command. Type the following 
statement: 


? 4*(2+3)" is the same as 4*5 REFERN- 


Notice that even spaces inside the quotation marks are printed 
on the screen. Type: 





’ a OVER HERE” -2&tURN- 


Printing in Different Colors 


The Commodore 128 is capable of displaying 16 different colors 
on the screen. You can change colors easily. All you do is hold 
down the CTRL key and press a numbered key between one and 
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eight on the top row of the main keyboard. Notice that the cursor 
changes color according to the numbered key you pressed. All 


the succeeding characters are displayed in the color you 


selected. Hold down the Commodore key and press a numbered 
key between one and eight, and eight additional colors are 
displayed on the screen. 


Table 3-1 lists the colors available on in C128 mode, for both 40- 
and 80-column screen formats. The table also shows the key 
sequence (CONTROL key plus number key, or & key plus 
number key) used to specify a given color. 


CONTROL + _ Color 


OnNOnp WM - 


CONTROL + 


OnNOnnr WD - 


2 


Black 
White 
Red 
Cyan 
Purple 
Green 
Blue 
Yellow 


OnNonr WD — 


Colors in 40-Column Format 


Q 


Color 


Black 

White 

Dark Red 
Light Cyan 
Light Purple 
Dark Green 
Dark Blue 
Light Yellow 


OnN on WDM —- 


Colors in 80-Column Format 


Color 


Orange 
Brown 

Light Red 
Dark Gray 
Medium Gray 
Light Green 
Light Blue 
Light Gray 


Color 


Dark Purple 
Brown 

Light Red 
Dark Cyan 
Medium Gray 
Light Green 
Light Blue 
Light Gray 


Using the Cursor Keys Inside Quotes with the PRINT 
Command 


When you type the cursor keys inside quotation marks, graphic 
characters are shown on the screen to represent the keys. These 
characters will NOT be printed on the screen when you press 
RETURN. Try typing a question mark (?), open quotes (SHIFTed 
2 key); then press either of the down cursor keys 10 times, enter 
the words “DOWN HERE”, and close the quotes. The line should 
look like this: 


?*lelelelelelelelelele: DOWN HERE” 


Now press RETURN. The Commodore 128 prints 10 blank lines, 
and on the eleventh line, it prints “DOWN HERE”. As this example 
shows, you Can tell the computer to print anywhere on your 
screen by using the cursor control keys inside quotation marks. 


BEGINNING TO PROGRAM 


So far most of the commands we have discussed have been 
performed in DIRECT mode. That is, the command was executed 
as soon as the RETURN key was pressed. However, most BASIC 
commands and functions can also be used in programs. 


What a Program Is 


A program is just a set of numbered BASIC instructions that tells 
your computer what you want it to do. These numbered 
instructions are referred to as statements or lines. 


Line Numbers 


The lines of a program are numbered so that the computer knows 
in what order you want them executed or RUN. The computer 
executes the program lines in numerical order, unless the 
program instructs otherwise. You can use any whole number 
from 0 to 63999 for a line number. Never use a comma in a line 
number. 


Many of the commands you have learned to use in DIRECT 
mode can be easily made into program statements. For example, 
type this: 


10 ? “COMMODORE 128” =REFURN= 


S19 


Notice the computer did not display COMMODORE 128 when 
you pressed RETURN, as it would do if you were using the PRINT 
command in DIRECT mode. This is because the number, 10, that 
comes before the PRINT symbol (?) tells the computer that you 
are entering a BASIC program. The computer just stores the 
numbered statement and waits for the next input from you. 


Now type RUN and press RETURN. The computer prints the 
words COMMODORE 128. This is not the same as using the 
PRINT command in DIRECT mode. What has happened here is 
that YOU HAVE JUST WRITTEN AND RUN YOUR FIRST BASIC 
PROGRAM as small as it may seem. The program is still in the 
computer's memory, SO you can run it as many times as you 
want. 


Viewing Your Program—The LIST Command 


Your one-line program is still in the C128 memory. Now clear the 
screen by pressing the SHIFT and CLR/HOME keys together. 
The screen is empty. At this point you may want to see the 
program listing to be sure it is still in memory. The BASIC 
language is equipped with a command that lets you do just this 
—the LIST command. 


Type LIST and press RETURN. The C128 responds with: 


10 PRINT “COMMODORE 128” 
READY. 


Anytime you want to see all the lines in your program, type LIST. 
This is especially helpful if you make changes, because you can 
check to be sure the new lines have been registered in the 
computer's memory. In response to the command, the computer 
displays the changed version of the line, lines, or program. Here 
are the rules for using the LIST command. 


—To see line N only, type LIST N and press RETURN. 
Substitute the line number you wish to see for N. 


—To see from line N to the end of the program, type LIST N- 
and press RETURN. 


—To see the lines from the beginning of the program to line 
N, type LIST-N and press RETURN. 


—To see from line N1 to line N2 inclusive, type LIST N1-N2 
and press RETURN. 


A Simple Loop—The GOTO Statement 


The line numbers in a program have another purpose besides 
putting your commands in the proper order for the computer. 
They serve as a reference for the computer in case you want to 
execute the command in that line repetitively in your program. 
You use the GOTO command to tell the computer to go to a line 
and execute the command(s) in it. Now type: 


20 GOTO 10 


When you press RETURN after typing line 20, you add It to your 
program in the computer's memory. 


Notice that we numbered the first line 10 and the second line 20. 
It is very helpful to number program lines in increments of 10 
(that is, 10, 20, 30, 40, etc.) in case you want to go back and add 
lines in between. You can number such added lines by fives (15, 
25 ...), or ones (1, 2 ...)—in fact, by any whole number —to keep 
the lines in the proper order. (See the RENUMBER and AUTO 
commands in the BASIC Encyclopedia.) 


Type RUN and press RETURN, and watch the words 
COMMODORE 128 move down your screen. To stop the 
message from printing on the screen, press the RUN/STOP key 
on the left side of your keyboard. 


The two lines that you have typed make up a simple program that 
repeats itself endlessly, because the second line keeps referring 
the computer back to the first line. The program will continue 
indefinitely unless you stop it or turn off the computer. 


Now type LIST =3=4#RNE The screen should say: 


10 PRINT “COMMODORE 128” 
20 GOTO 10 
READY. 


Your program is still in memory. You can RUN it again if you want 
to. This is an important difference between PROGRAM mode and 
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DIRECT mode. Once a command is executed in DIRECT mode, it 
is no longer in the computer's memory. Notice that even though 
you used the ? symbol! for the PRINT statement, your computer 
has converted it into the full command. This happens when you 
LIST any command you have abbreviated in a program. 


Clearing the Computer’s Memory—The NEW Command 


Anytime you want to start all over again or erase a BASIC 
program in the computer's memory, just type NEW and press 
RETURN. This command clears out the computer's BASIC 
memory, the area where programs are stored. 


Using Color in a Program 


To select color within a program, you must include the color 

selection information within a PRINT statement. For example, 
clear your computer's memory by typing NEW and pressing 

RETURN, then type the following, being sure to leave space 

between each letter: 


10 PRINT “RAIN B O W” =SEfeRNE 


Now type line 10 again but this time hold down the CTRL key and 
press the 1 key directly after entering the first set of quote marks. 
Release the CTRL key and type the “R”. Now hold down the 
CTRL again and press the 2 key. Release the CTRL key and type 
the “A”. Next hold down the CTRL again and press the 3 key. 
Continue this process until you have typed all the letters in the 
word RAINBOW and selected a color between each letter. Press 
the SHIFT and the 2 keys to type a set of closing quotation marks 
and press the RETURN key. Now type RUN and press the 
RETURN key. The computer displays the word RAINBOW with 
each letter in a different color. Now type LIST and press the 
RETURN key. Notice the graphic characters that appear in the 
PRINT statement in line 10. These characters tell the computer 
what color you want for each printed letter. Note that these 
graphic characters do not appear when the Commodore 128 
PRINTs the word RAINBOW in different colors. 


The color selection characters, known as control characters, in 
the PRINT statement in line 10 tell the Commodore 128 to 
change colors. The computer then prints the characters that 
follow in the new color until another color selection character is 
encountered. While characters enclosed in quotation marks are 
usually PRINTed exactly as they appear, control characters are 
only displayed within a program LISTing. 
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Editing Your Program 


The following paragraphs will help you to type in your programs 
and make corrections and additions to them. 


Erasing a Line from a Program 


Use the LIST command to display the program you typed 
previously. Now type 10 and press RETURN. You just erased line 
10 from the program. LIST your program and see for yourself. If 
the old line 10 Is still on the screen, move the cursor up so that it 
is blinking anywhere on that tine. Now, if you press RETURN, line 
10 is back in the computer's memory. 


Duplicating a Line 


Hold down the SHIFT key and press the CLR/HOME key on the 
upper right side of your keyboard. This will clear your screen. 
Now LIST your program. Move the cursor up again so that it is 
blinking on the ‘“‘O” in the line numbered 10. Now type a 5 and 
press RETURN. You have just duplicated (i.e., copied) line 10. 
The duplicate line is numbered 15. Type LIST and press RETURN 
to see the program with the duplicated lines. 


Replacing a Line 


You can replace a whole line by typing in the old line number 
followed by the text of the new line, then pressing RETURN. The 
old version of the line will be erased from memory and replaced 
by the new line as soon as you press RETURN. 


Changing a Line 


Suppose you want to add something in the middle of a line. 
Simply move the cursor to the character or space that 
immediately follows the spot where you want to insert the new 
material. Then hold down the SHIFT key and the INST/DEL key 
together until there is enough space to insert your new 
characters. 


Try this example. Clear the computer's memory by typing NEW 
and pressing RETURN. Then type: 


10 ? “MY 128 1S GREAT” =REFuRN- 


Let's say that you want to add the word COMMODORE in front of 
the number 128. Just move the cursor so that it is blinking on the 
“1” in 128. Hold down the SHIFT and INST/DEL keys until you 
have enough room to type in COMMODORE (don't forget to leave 
enough room for a space after the E). Then type in the word 
COMMODORE. 


MATHEMATICAL OPERATIONS 


If you want to delete something in a line (including extra blank 
Spaces), move the cursor to the character following the material 
you want to remove. Then hold down the INST/DEL key by itself. 
The cursor will move to the left, and characters or spaces will be 
deleted as long as you hold down the INST/DEL key. 


Mathematical Operations 


You can use the PRINT command to perform calculations like 
addition, subtraction, multiplication, division and exponentiation. 
You type the calculation after the PRINT command. 

Addition and Subtraction 

Try typing these examples: 

PRINT 6+ 4 367gRA 

PRINT 50 - 20 -REFuR 

PRINT 10+ 15-5 tgRwe 

PRINT 75 - 100 =3673Re- 

PRINT 30 + 40,55 - -REfeRRE 
PRINT 30 + 40;55 - 25 -2ETuRN 


Notice that the fourth calculation (75-100) resulted in a negative 
number. Also notice that you can tell the computer to make more 
than one calculation with a single PRINT command. You can use 
either a comma or a semicolon in your command, depending on 
whether or not you want your results printed tabulated or next to 
each other. 
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Multiplication and Division 


Find the asterisk key (*) on the right side of your keyboard. This 
is the symbol that the Commodore 128 uses for multiplication. 
The slash (/) key, located next to the right SHIFT key, is used for 
division. 


Try these examples: 


PRINT 5*3 RETURN 
PRINT 100/2 RETURN 


Exponentiation 


Exponentiation means to raise a number to a power. The up 
arrow key (t), located next to the asterisk on your keyboard, is 
used for exponentiation. If you want to raise a number to a power, 
use the PRINT command, followed by the number, the up arrow 
and the power, in that order. For example, to find out what 3 
squared is, type: 


PRINT 312 =REtgRN 


Order of Operations 


You have seen how you can combine addition and subtraction in 
the same PRINT command. If you combine multiplication or 
division with addition or subtraction operations, you may not get 
the result you expect. For example, type: 


PRINT 4+ 6/2 =REFURNE 


If you assumed you were dividing 10 by 2, you were probably 
surprised when the computer responded with the answer 7. The 
reason you got this answer is that multiplication and division 
operations are performed by the computer before addition or 
subtraction. Multiplication and division are said to take 
precedence over addition and subtraction. It doesn't matter in 
what order you type the operation. In computing, the order in 
which mathematical operations are performed is known as the 
order of operations. 


Exponentiation, or raising a number to a power, takes 
precedence over the other four mathematical operations. For 
example, if you type: 
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PRINT 16/412 -REFURRE 


the Commodore 128 responds with a 1 because it squares the 4 
before it divides 16. 


Using Parentheses to Define the Order of Operations 


You can tell the Commodore 128 which mathematical operation 
you want performed first by enclosing that operation in 
parentheses in the PRINT command. For instance, in the first 
example above, if you want to tell the computer to add before 
dividing, type: 

PRINT (4+ 6)/2 RERIRN 


This gives you the desired answer, 5. 


If you want the computer to divide before Squaring in the second 
example, type: 


PRINT (16/4)12 -REFURN 
Now you have the expected answer, 16. 
If you don't use parentheses, the computer performs the 
calculations according to the above rules. When all operations in 


a calculation have equal precedence, they are performed from 
left to right. For example, type: 


PRINT 4*5/10*6 -RERIRN- 


Since the operations in this example are performed in order from 
left to right, the result is 12 (4*5 = 20... 20/10 = 2 ...2*6 = 12), If 
you want to divide 4*5 by 10*6 you type: 


PRINT (4*5)/(10*6) -REFURN- 
The answer is now 333333333. 


CONSTANTS, VARIABLES AND STRINGS 


Constants 


Constants are numeric values that are permanent: that is, they do 
not change in value over the course of an equation or program. 
For example, the number 3 is a constant, as is any number. This 
statement illustrates how your computer uses constants: 


S222 


10 PRINT 3 


No matter how many times you execute this line, the answer will 
always be 3. 


Variables 


Variables are values that can change over the course of an 
equation or program statement. There is a part of the computer's 
BASIC memory that is reserved for the characters (numbers, 
letters and symbols) you use in your program. Think of this 
memory as a number of storage compartments in the computer 
that store information about your program; this part of the 
computer's memory is referred to as variable storage. Type in this 
program: 


10 X=5 
20 ?X 


Now RUN the program and see how the computer prints a 5 on 
your screen. You told the computer in line 10 that the letter X will 
represent the number 5 for the remainder of the program. The 
letter X is called a variable, because the value of X varies 
depending on the value to the right of the equals sign. We call 
this an assignment statement because now there is a storage 
compartment labeled X in the computer's memory, and the 
number 5 has been assigned to it. The = sign tells the computer 
that whatever comes to the right of it will be assigned to a storage 
compartment (a memory location) labeled with the letter X to the 
left of the equals sign. 


The variable name on the left side of the = sign can be either one 
or two letters, or one letter and one number (the letter MUST 
come first). The names can be longer, but the computer only 
looks at the first two characters. This means the names PA and 
PART would refer to the same storage compartment. Also, the 
words used for BASIC commands (LOAD, RUN, LIST, etc.) or 
functions (INT, ABS, SQR, etc.) cannot be used as names in your 
programs. Refer to the BASIC Encyclopaedia in Chapter 5 if you 
have any questions about whether a variable name is a BASIC 
keyword. Notice that the = in assignment statements is not the 
same as the mathematical symbol meaning “equals”, but rather 
means allocate a variable (storage compartment) and assign a 
value to it. 
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In the sample program you just typed, the value of the variable X 
remains at 5 throughout. You can put calculations to the right of 
the = sign to assign the result to a variable. You can mix text with 
constants in a PRINT statement to identify them. Type NEW and 
press RETURN to clear the Commodore 128’s memory; then try 
this program: 


10 A = 3*100 
20 B = 3*200 
30 ?“A IS EQUAL TO A 
40 ?“B 1S EQUAL TO ’’B 


Now there are two variables, labeled A and B, in the computer's 
memory, containing the numbers 300 and 600 respectively. If, 
later in the program, you want to change the value of a variable, 
just put another assignment statement in the program. Add these 
lines to the program above and RUN it again. 


50 A = 900*30/10 
60 B = 95 + 32 + 128 
70 GOTO 30 


You'll have to press the STOP key to halt the program. 


Now LIST the program and trace the steps taken by the 
computer. First, it assigns the value to the right of the = sign in 
line 10 to the letter A. It does the same thing in line 20 for the 
letter B. Next, it prints the messages in lines 30 and 40 that give 
you the values of A and B. Finally, it assigns new values to A and 
B in lines 50 and 60. The old values are replaced and cannot be 
recovered unless the computer executes lines 10 and 20 again. 
When the computer is sent to line 30 to begin printing the values 
of A and B again, it prints the new values calculated in lines 50 
and 60. Lines 50 and 60 reassign the same values to A and B 
and line 70 sends the computer back to line 30. This is called an 
endless loop, because lines 30 through 70 are executed over and 
over again until you press the RUN/STOP key to halt the 
program. Other methods of looping are discussed later in this and 
the following two chapters. 


Strings 


A string is a character or group of characters enclosed in quotes. 
These characters are stored in the computer's memory as a 
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variable in much the same way numeric variables are stored. You 
can also use variable names to represent strings, just aS you use 
them to represent numbers. When you put the dollar sign ($) after 
the variable name, it tells the computer that the name is for a 
string variable, and not a numeric variable. 


Type NEW and press RETURN to clear your computer's memory, 
then type in the program below: 


10 A$ = “COMMODORE “ 


20 X = 128 
30 B$ = ‘““ COMPUTER” 
40 Y=1 


50 ? “THE ”A$;X;B$"' IS NUMBER ”’Y 


See how you can print numeric and string variables in the same 
statement? Try experimenting with variables in your own short 
programs. 


You Can print the value of a variable in DIRECT mode, after the 
program has been RUN. Type ?A$;B$;X;Y after running the 
program above and see that those three variable values are still 
in the computer's memory. 


If you want to clear this area of BASIC memory but still leave your 
program intact, use the CLR command. Just type CLR CRETURN> 
and all constants, variables and strings are erased. But when you 
type LIST, you can see the program is still in memory. The NEW 
command discussed earlier erases both the program and the 
variables. 


SAMPLE PROGRAM 


Here is a Sample program incorporating many of the techniques 
and commands discussed in this section. 


This program calculates the average of three numbers (X, Y and 
Z) and prints their values and their averages on the screen. You 
can edit the program and change the calculations in line 10 
through 30 to change the values of the variables. Line 40 adds 
the variables and divides by 3 to get the average. Note the use of 
parentheses to tell the computer to add the numbers before it 
divides. 
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TIP: Whenever you are using more than one set of 
parentheses in a statement, it's a good Idea to count the 
number of left parentheses and right parentheses to make 
sure they are equal. 


10 X = 46 
20 Y=73 
30 Z=114 


40 A=(X+Y+2Z)/3 
50?“ THE AVERAGE OF’’X;Y;“‘AND “Z;“IS”A; 
60 END 


STORING AND REUSING YOUR PROGRAM 


Once you have created your program, you will probably want to 
store it permanently so you will be able to recall and use it at 
some later time. To do this, you'll need either a Commodore disk 
drive or the Commodore 1530 Datassette. 


You will learn several commands that let you communicate 
between your computer and your disk drive or Datassette. These 
commands are constructed with the use of a command word 
followed by several parameters. Parameters are letters, words or 
symbols in a command that supply specific information to the 
computer, such as a filename, or a numeric variable that 
specifies a device number. Each command may have several 
parameters. For example, the parameters of the disk format 
command include a name for the disk and an identifying number 
or code, plus several other parameters. Parameters are used in 
almost every BASIC command: some are variables which change 
and others are constant. These are the parameters that supply 
disk information to the C128 and disk drive: 


Disk Handling Parameters 


disk name— arbitrary 16 character identifying name 
you supply. 

file name— arbitrary 16 character identifying name 
you supply. 

i.d. number— arbitrary two-character identifying code 
you supply 

drive number— must use 0 fora single disk drive, O or 1 


in a dual drive. 


device number— a preassigned number for a peripheral 
device. For example, the device number 
for a Commodore disk drive is 8. 


Formatting a Disk—The HEADER Command 


To store programs on a new (or blank) disk, you must first 
prepare the disk to receive data. This is called “formatting” the 
disk. NOTE: Make sure you turn on the disk drive before inserting 
any disk. 


The formatting process divides the disk into sections called 
tracks and sectors. A table of contents, called a directory, is 
created. Each time you store a program on disk, the name you 
assign to that program will be added to the directory. 


The Commodore 128 has two kinds of formatting commands. 
One can be used only in C128 mode, and one can be used in 
both C64 and C128 mode. The following paragraphs describe 
C128 mode format commands here. See Chapter III on C64 
mode for more information about C64 programming and disk 
handling. 


The command that formats a diskette is called the HEADER 
command. It has a long form and a short form. To format a blank 
(new) disk, you MUST use the long form as follows: 


HEADER ‘“‘diskname’’,li.d.[,Ddrive number] [,{ON]U device 
number] 


After the word HEADER, you type a name of your choice for the 
disk, within quotes. You can choose any name with up to 16 
characters. You should choose disk names that help you identify 
what will be stored on the disk. 

Follow the diskname with a comma and the letter “Il. Now a two 
character |.d., followed by a comma. Your disk |.d. does not have 
to be numbers; you can also choose letters. You may want to 
develop a consecutive coding system for your disks, such as A1, 
A2, B1, B2. 

If you have one single disk drive, just press RETURN at this point 
since the Commodore 128 automatically assumes the drive 
number is 0 and the device number is 8. You can specify these 
parameters if you have more than one drive or a dual drive. 
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The next parameter in the command selects the drive number. 
Press the 'D” key and if you have a single disk drive, press the 
zero key followed by a comma. Dual drives are labeled 0 and 1. 
The device number parameter starts with the letter U so press 
the “U" key followed by the preassigned device number for a 
Commodore disk drive which is 8. 


Here is an example of the long form of the HEADER command: 


HEADER“RECS”,IA1,00,U8 RETERN: 


This command formats the diskette, calling it RECS, the I.d. 
number A1, on drive 0, unit 8. 


The default values for disk drive (0) and device number (8) will be 
used if none are supplied. This is an acceptable long form of the 
HEADER command: 


HEADER “MYDISK’’, I51 REFURN- 


The HEADER command can also be used to erase all data from 
a used disk, so the disk can be reused as if it were a brand new 
disk. Be careful that you don't erase a disk that contains data you 
may want someday. 


The quick form of the HEADER command can be used if the disk 
was previously formatted with the long form of the HEADER 
command. 

The quick form clears the directory, erasing all data in the same 
way as the long form, but keeps the same i.d. aS was previously 
used. Here ts what the quick HEADER might look like: 


HEADER “NEWPROGS” 





SAVEing on Disk 


In C128 mode, you can store your program on disk by using 
either of the following commands: 


DSAVE‘‘PROGRAM NAME” RETURN” 


SAVE“PROGRAM NAME”,8 — 


Either command can be used. Remember that the character 
sequence DSAVE" can be displayed on the screen by pressing 
the function key labeled F5, or you can type the sequence 
yourself. The program name can be any name you choose, up to 
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16 characters long. Be sure to enclose the program name in 
quotes. You cannot put two programs with the same name on the 
same disk. If you do, the second program will not be accepted; 
the disk will retain the first one. In the second example, the 8 
indicates that you are saving your program on device number 8. 
You do not need the 8 with DSAVE, because the computer 
automatically assumes you are using device number 8. 


SAVEing on Cassette 


If you are using a Datassette to store your program, insert a blank 
tape in the recorder, rewind the tape if necessary, and type: 


SAVE “PROGRAM NAME” =REtGgRH- 


You must type the word SAVE, followed by the program name. 
The program name can be any name you choose up to 16 
characters. 


NOTE: The 40 column screen will go blank while the 
program is being SAVEd, but returns to normal when the 
process is completed. 


Unlike disk, you can save two programs to tape under the same 
name. However when you load it back into the computer, the first 
program sequentially on the tape will be loaded, so avoid giving 
programs the same name. 


Once a program has been SAVEd, you can LOAD it back into the 
computer's memory and RUN it anytime you wish. 


LOADing from Disk 


Loading a program simply copies the contents of the program 
from the disk into the computer’s memory. If a BASIC program 
was already in memory before you issued the LOAD commana, it 
IS erased. 


To load your BASIC program from a disk, use either of the 
following commands in C128 mode: 


DLOAD‘‘PROGRAM NAME” -SETUGRN- 
LOAD‘PROGRAM NAME’”’,8 -REFERN- 
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Remember, in C128 mode you can use the F2 function key 
(which you activate by pressing SHIFT and F1 together) to 
display the sequence DLOAD", or you can type the letters 
yourself. In the second example, the 8 indicates to the computer 
that you are loading from device number 8. Again, like DSAVE, 
DLOAD assumes the disk-drive device number is 8. Be careful to 
type the program name exactly as you typed it when SAVEing the 
program, or the computer will respond “FILE NOT FOUND.” 


Once the program is loaded, type RUN to execute. The 
Commodore 128 has a special form of the RUN command used 
to LOAD and RUN the program in C128 mode with one 
command. Type RUN, followed by the name of the program (also 
known as the filename) in quotes: 


RUN“MYPROG” =REtURN- 


LOADing from Cassette Tape 
To LOAD your program from cassette tape, type: 


LOAD “PROGRAM NAME” -RETtERN- 


If you do not know the name of the program, you can type: 
LOAD EfURN 


and the next program on the tape will be found. While the 
Datassette is searching for the program the 40 column screen is 
blank. When the program is found, the screen displays 


FOUND PROGRAM NAME 


To actually load the program, you then press the Commodore 
key, or in 128 mode press the space bar to find the next program 
on the tape. 


You can use the counter on the Datassette to identify the starting 
position of the programs. Then, when you want to retrieve a 
program, simply wind the tape forward from 000 to the program's 
start location, and type: 


LOAD RETURN: 
In this case you don't have to specify the PROGRAM NAME: your 


program will oad automatically because it is the next program on 
the tape. 
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Other Disk-Related Commands 
Verifying a Program 


To verify that a program has been correctly saved, use the 
following command in C128 mode. 


DVERIFY““PROGRAM NAME” -REtgRN- 
If the program in the computer is identical to the one on the disk, 
the screen display will respond with the letters “OK.” 
The VERIFY command also works for tape programs. You type: 
VERIFY“PROGRAM NAME” -3&?#aN- 


You do not enter the comma and a device number 


Displaying Your Disk Directory 


In C128 mode, you can see a list or directory of the programs on 
your disk by using the following command: 


DIRECTORY -8&?9uRN 


This lists the contents of the directory. The easy way is to press 
the F3 function key. When you press F8, the C128 displays the 
word “DIRECTORY” and performs the command. 





For further information on SAVEing and LOADing your programs, 
or other disk related information refer to your Datassette or disk 
drive manual. Also consult the LOAD and SAVE command 
descriptions in the Chapter V, BASIC 7.0 Encyclopedia 


wk kk kkk kk Kk 


You now know something about the BASIC language and some 
elementary programming concepts. The next section builds on 
these concepts, introducing additional commands, functions and 
techniques that you can use to program in BASIC 
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This section describes how to use a number of powerful BASIC 
commands, functions and programming techniques that can be 
used in both C128 and C64 modes. 


These commands and functions allow you to program repeated 
actions through looping and nesting techniques; handle tables of 
values; branch or jump to another section of a program, and 
return from that section; assign varying values to a quantity—and 
more. Examples and sample programs show just how these 
BASIC concepts work and interact. 


COMPUTER DECISIONSTHE IF-THEN STATEMENT 


Now that you know how to change the values of variables, the 
next step is to have the computer make decisions based on 
these updated values. You do this with the IF-THEN statement. 
You tell the computer to execute a command only IF a condition 
is true (e.g., IF X=5). The command you want the computer to 
execute when the condition is true comes after the word THEN in 
the statement. Clear your computer’s memory by typing NEW and 
pressing RETURN, then type in this program: 


10 J=0 

20 J=J+1 

30 ? J,’"COMMODORE 128” 
40 IF J=5 THEN GOTO 60 
50 GOTO 20 

60 END 


You no longer have to press the STOP key to break out of a 
looping program. The IF-THEN statement tells the computer to 
keep printing “COMMODORE 128” and incrementing 
(increasing) J until J=5 is true. When an IF condition is false, the 
computer jumps to the next line of the program, no matter what 
comes after the word THEN. 


Notice the END command in line 60. It is good practice to put an 


END statement as the last line of your program. It tells the 
computer where to stop executing statements. 
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Below is a list of comparison symbols that may be used in the IF 
statement and their meanings: 


SYMBOL MEANING 

= EQUALS 

> GREATER THAN 

< LESS THAN 

<- NOT EQUAL TO 

>= GREATER THAN OR EQUAL TO 
<= LESS THAN OR EQUAL TO 


You should be aware that these comparisions work in expected 
mathematical ways with numbers. There are different ways to 
determine if one string is greater than, less than, or equal to 
another. You can learn about these ‘‘string handling” functions by 
referring to Chapter V, BASIC 7.0 Encyclopaedia. 


Section 5 describes some powerful extensions of the IF- THEN 
concept, consisting of BASIC 7.0 commands like BEGIN, BEND, 
and ELSE. 


Using the Colon 


A very useful tool in programming is the colon (:). You can use 
the colon to separate two (or more) BASIC commands on the 
same line. 


Statements after a colon on a line will be executed in order, from 
left to right. In one program line you can put as many statements 
as you can fit onto 160 characters, including the line number. 
This is equivalent to four full screen lines in 40-column format, 
and two full lines in 80-column format. This provides an excellent 
opportunity to take advantage of the THEN part of the IF-THEN 
statement. You can tell the computer to execute several 
commands when your IF condition is true. Clear the computer's 
memory and type in the following program: 


10 N=1 
20 IF N<5 THEN PRINT N;“LESS THAN 5”:GOTO 40 


30 ? N; ‘GREATER THAN OR EQUAL TO 5” 
40 END 
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Now change line 10 to read N=20, and RUN the program again. 
Notice you can teil the computer to execute more than one 
Statement when N is Jess than 5. You can put any statement(s) 
you want after the THEN command. Remember that the GOTO 
40 will not be reached until N<5 is true. Any command that 
should be followed whether or not the specified condition is met 
should appear on a separate line. 


LOOPS—THE FOR-NEXT COMMAND 


In the program used for the IF-THEN example, we made the 
computer print Commodore five times by telling it to increase or 
“increment” the variable J by units of one, until the value of J 
equalled five; then we ended the program. There is a simpler way 
to do this in BASIC. We can use a FOR-NEXT loop, like this: 


10 FOR J=1TO5 

20 ?J, “COMMODORE 128” 
30 NEXT J 

40 END 


Type and RUN this program and compare the result with the 
result of the IF-THEN program—they are the same. In fact, the 
steps taken by the computer are almost identical for the two 
programs. The FOR-NEXT loop is a very powerful programming 
tool. You can specify the number of times the computer should 
repeat an action. Let’s trace the computer's steps for the program 
above. 


First, the computer assigns a value of 1 to the variable J. The 5 in 
the FOR statement in line 10 tells the computer to execute all 
statements between the FOR statement and the NEXT statement, 
until J is equal to 5. In this case there is just one statement—the 
PRINT statement. 


The computer first assigns 1 to J, it then goes on to execute the 
PRINT statement. When the computer reaches the NEXT J 
statement, J is incremented and compared with 5. lf J has not 
exceeded 5 the computer loops back to the PRINT statement. 
After five executions of this loop the value of J exceeds 5, the 
program drops down to the statement that comes immediately 
after the NEXT statement and continues from there. In this case 
the following statement is the END command, so the program 
stops. 
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Empty loops—lInserting delays in a program 


Before you proceed any further, it will be helpful to understand 
about loops and some ways they are used to get the computer to 
do what you want. You can use a loop to slow down the 
computer (by now you have witnessed the speed with which the 
computer executes commands). See if you can predict what this 
program will do before you run it. 


10 A$=““COMMODORE 128” 
20 FOR J=1 TO 20 

30 PRINT 

40 FOR K=1 TO 1500 

50 NEXT K 

60 PRINT A$ 

70 NEXT J 

80 END 


Did you get what you expected? The loop contained in lines 40 
and 50 tells the computer to count to 1500 before executing the 
remainder of the program. This is known as a delay loop and is 
often useful. Because it is inside the main loop of the program, it 
is called a nested loop. Nested loops can be very useful when 
you want the computer to perform a number of tasks in a given 
order, and repeat the entire sequence of commands a certain 
number of times. 


Section 5 describes an advanced way to insert delays through 
use of the new BASIC 7.0 command, SLEEP. 


The STEP Command 


You can tell the computer to increment your counter by units (e.g. 
10, 0.5 or any other number). You do this by using a STEP 
command with the FOR statement. For example, if you want the 
computer to count by tens to 100, type: 


10 FOR X=0 TO 100 STEP 10 
20 ?X 
30 NEXT 
Notice that you do not need the X in the NEXT statement if you 


are only executing one loop at a time—this is discussed later in 
this section. Also, note that you do not have to increase (or 
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“increment’’) your counter—you can decrease (or ‘‘decrement’) 
itas well. For example, change line 10 in the program above to 
read: 


10 FOR X=100 TO 0 STEP - 10 
The computer will count backward from 100 to 0, in units of 10. 


If you don’t use a STEP command with a FOR statement, the 
computer will automatically increment the counter by units of 1. 


The parts of the FOR-NEXT command are: 


FOR — word used to indicate beginning of loop 
X — counter variable; any number variable can be used 
1 — starting value; may be any number, positive or 
negative 
TO — connects starting value to ending value 
100 — ending value; may be any number, positive 
or negative 
STEP — indicates an increment other than 1 will be 
used 
2 — increment; can be any number positive or negative 


Section 5 describes DO/LOOP, a new, more powerful BASIC 7.0 
command to perform a similar task to the STEP command. 


INPUTTING DATA 
The INPUT Command 


Assigning a value to a Variable 


Clear the computer's memory by typing NEW and pressing 
RETURN, and then type and RUN this program. 


10 K=10 

20 FOR I=1 TO K 

30 ? “COMMODORE 128” 
40 NEXT 


In this program you can change the value of K in line 10 to make 
the computer execute the loop as many times as you want it to. 
You have to do this when you are typing in the program, before it 
is RUN. What if you wanted to be able to tell the computer how 
many times to execute the loop at the time the program is RUN? 
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In other words, you want to be able to change the value of the 
variable K each time you run the program, without having to 
change the program itself. We call this the ability to interact with 
the computer. You can have the computer ask you how many 
times you want it to execute the loop. To do this, use the INPUT 
command. For example, replace line 10 in the program with: 


10 INPUT K 


Now when you RUN the program, the computer responds with a 
? to let you know it is waiting for you to enter what you want the 
value of K to be. Type 15 and press RETURN. The computer will 
execute the loop 15 times. 


Prompt messages 


You can also make the computer print a message in an INPUT 
statement to tell you what variable it’s waiting for. Replace line 10 
with: 


10 INPUT‘;PLEASE ENTER A VALUE FOR K’”’;K 


Remember to enclose the message to be printed in quotes. This 
message is called a prompt. Also, notice that you must use a 
semicolon between the ending quote marks of the prompt and 
the K. You may put any message you want in the prompt, Dut the 
INPUT statement must be 160 characters or less, just as any 
BASIC command must. 


The INPUT statement can also be used with string variables. The 
same rules that apply for numeric variables apply for strings. 
Don't forget to use the $ to identify all your string variables. Clear 
your computer's memory by typing NEW and pressing RETURN. 
Then type in this program. 


10 INPUT“WHAT IS YOUR NAME”’;N$ 
20 ? “HELLO ”’;N$ 


Now RUN the program. When the computer prompts “WHAT IS 
YOUR NAME?”, type your name. Don't forget to press RETURN 
after you type your name. 


Once the vatue of a variable (numeric or string) has been 
inserted into a program through the use of INPUT, you can refer 
to it by its variable name any time in the program. Type ?N$ 
<RETURN>—your computer remembers your name! 


4-8 


The GET command 


There are other BASIC commands you can use in your program 
to interact with the computer. One is the GET command and ts 
similar to INPUT. To see how the GET command works, clear the 
computer's memory and type this program. 


10 GET A$ 

20 IF A$=“*” THEN 10 
30 2? A$ 

40 END 


When you type RUN and press RETURN, nothing seems to 
happen. The reason is that the computer is waiting for you to 
press a key. The GET command, in effect, tells the computer to 
check the keyboard and find out what character or key Is being 
pressed. The computer is satisfied with a null character (that is, 
no character). This is the reason for line 20. This line tells the 
computer that if it gets a null character, indicated by the two 
double quotes with no space between them, it should go back to 
line 10 and try to GET another character. This loop continues 
until you press a key. The computer then assigns the character 
on that key to A$. 


The GET command is very important because you can use it, in 
effect, to program a key on your keyboard. The example below 
prints a message on the screen when Q is pressed. Type the 
program and RUN it. Then press Q and see what happens. 


10 ?“PRESS Q TO VIEW MESSAGE” 

20 GET A$ 

30 IF A$="'” THEN 20 

40 IF A$=‘‘Q” THEN 60 

50 GOTO 20 

60 FOR I=1 TO 25 

70 ? “NOW I CAN USE THE GET STATEMENT” 
80 NEXT 

90 END 


Notice that if you try to press any key other than the Q, the 
computer will not display the message, but will go back to line 20 
to GET another character. 
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Section 5 describes how to use the GETKEY statement, which is 
a new and more powerful BASIC 7.0 command that can be used 
to perform a similar task. 


Sample program 


Now that you know how to use the FOR-NEXT loop and the 
INPUT command, clear the computer's memory by typing NEW 
“REFURB , then type the following program: 


10 T=0 

20 INPUT“HOW MANY NUMBERS”;N 

30 FOR J=1 TON 

40 INPUT“PLEASE ENTER A NUMBER ”;X 
50 T=T+X 

60 NEXT 

70 A=T/N 

80 PRINT 

90 ? “YOU HAVE “;N’” NUMBERS TOTALING ”;T 
100 ? “AVERAGE =”;A 

110 END 


This program lets you tell the computer how many numbers you 
want to average. You can change the numbers every time you 
run the program without having to change the program itself. 


Let's see what the program does, line by line: 


Line 10 assigns a value of 0 to T (which will be the running 
total of the numbers). 

Line 20 lets you determine how many numbers to average, 
stored in variable N. 

Line 30 tells the computer to execute a loop N times. 

Line 40 lets you type in the actual numbers to be averaged. 

Line 50 adds each number to the running total. 

Line 60 tells the computer to increment the counter (J) and 
loop back to line 30 while the counter (J) <= N. 

Line 70 divides the total by the amount of numbers you 
typed in (N) after the loop has been executed N times. 

Line 80 prints a blank line on the screen. 

Line 90 prints the message that gives you the amount of 
numbers and their total. 

Line 100 prints the average of the numbers. 

Line 110 tells the computer that your program Is finished. 
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The READ-DATA command 


There is another powerful way to tell the computer what numbers 
or characters to use in your program. You can use the READ 
statement in your program to tell the computer to get a number or 
character(s) from the DATA statement. For example, if you want 
the computer to find the average of five numbers, you can use 
the READ and DATA statements this way: 


10 T=0 

20 FOR J=1TO5 

30 READ X 

40 T=T+X 

50 NEXT 

60 A=T/5 

70 ? “AVERAGE =”;A 
80 END 

90 DATA 5,12,1,34,18 


When you run the program, the computer will print AVERAGE = 
14, The program uses the variable T to keep a running total, and 
calculates the average in the same way as the INPUT average 
program. The READ-DATA average program, however, finds the 
numbers to average on a DATA line. Notice line 30, READ X. The 
READ command tells the computer there must be a DATA 
statement in the program. It finds the DATA line, and uses the 
first number as the current value for the variable X. The next time 
through the loop the second number in the DATA statement will 
be used as the value for X, and so on. 


You Can put any number you want in a DATA statement, but you 
cannot put calculations ina DATA statement. The DATA 
statement can be anywhere you want in the program—even after 
the END statement. This is because the computer never really 
executes the DATA statement; it just refers to it. Be sure to 
separate your data items with commas, but be sure not to put a 
comma between the word DATA and the first number in the list. 


If you have more than one DATA statement in your program, the 
computer will start READing from the first DATA statement when 
the program is RUN. The computer uses a pointer to remind itself 
which piece of data it read last. After the computer reads the first 
number in the DATA statement, the pointer moves to the next 
number. When the computer comes to the READ statement 
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again, it assigns the value the pointer indicates to the variable 
name in the READ statement. 


You can use as many READ and DATA statements as you need 
in a program, but make sure there is enough data in the DATA 
statements for the computer to read. Remove one of the numbers 
from the DATA statement in the last program and run it again. 
The computer responds with ?0UT OF DATA ERROR IN 30. 
What happened is that when the computer executed the loop for 
the fifth time, there was no data for it to read. That is what the 
error message is telling you. Putting too much into the DATA 
statement doesn't create a problem because the computer never 
realizes the extra data exists. 


The RESTORE Command 


You can use the RESTORE command in a program to reset the 
data pointer to the first piece of data if you need to. Replace the 
END statement (line 80) in the program above with: 


80 RESTORE 
and add 
85 GOTO 10 


Now RUN the program. The program will run continuously using 
the same DATA statement. NOTE: If the computer gives you an 
OUT OF DATA ERROR message, it is because you forgot to 
replace the number that you removed previously from the DATA 
statement, so the data is all! used before the READ statement has 
been executed the specified number of times. 


You can use DATA statements to assign values to string 
variables. The same rules apply as for numeric data. Clear the 
computer’s memory and type the following program: 


10 FOR J=1TO3 

20 READ A$ 

30 ? A$ 

40 NEXT 

50 END 

60 DATA COMMODORE, 128,COMPUTER 
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If the READ statement calls for a string variable, you can place 
letters or numbers in the DATA statement. Notice however, that 
since the computer is READing a string, numbers will be stored 
as a String of characters, not as a value which can be 
manipulated. Numbers stored as strings can be printed, but not 
used in calculations. Also, you cannot place letters ina DATA 
statement if the READ statement calls for a number variable. 


Using Arrays 


You have seen how to use READ-DATA to provide many values 
for a variable. But what if you want the computer to remember all 
the data in the DATA statement instead of replacing the value of 
a variable with the new data? What If you want to be able to recall 
the third number, or the second string of characters? 


Each time you assign a new value to a variable, the computer 
erases the old value in the variable’s box in memory and stores 
the new value in its place. You can tell the computer to reserve a 
row of boxes in memory and store every value that you assign to 
that variable in your program. This row of boxes Is called an 
array. 


Subscripted Variables 


If the array contains all of the values assigned to the variable X in 
the READ-DATA example, it is called the X array. The first value 
assigned to X in the program is named X(1), the second value is 
X(2), and so on. These are called subscripted variables. The 
numbers in the parentheses are called subscripts. You can use a 
variable or a calculation as a subscript. The following is another 
version of the averaging program, this time using subscripted 
variables. 


5 DIM X(5) 
10 T=0 

20 FOR J=1T0 5 
30 READ X(J) 


70 ? “AVERAGE =”;A 
80 END 
90 DATA 5,12,1,34,18 
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Notice there are not many changes. Line 5 is the only new 
statement. It tells the computer to set aside five boxes in memory 
for the X array. Line 30 has been changed so that each time the 
computer executes the loop, it assigns a value from the DATA 
statement to the position in the X array that corresponds to loop 
counter (J). Line 40 calculates the total, just as it did before, but 
you must use a subscripted variable to do it. 


After you run the program, if you want to recall the third number, 
type ?X(3)<RETURN>. The computer remembers every number 
in the array X. You can create string arrays to store the 
characters in string variables the same way. Try updating the 
COMMODORE 128 COMPUTER READ-DATA program so the 
computer will remember the elements in the A$ array. 


5 DIM A$(3) 

10 FOR J=1T0 3 
20 READ A$(J) 
30 ? A$(J) 


60 DATA COMMODORE,C128,COMPUTER 


TIP: You do not need the DIM statement in your program unless 
the array you use has more than 10 elements. See 
DIMENSIONING ARRAYS. 


Dimensioning Arrays 


Arrays can be used with nested loops, so the computer can 
handie data in a more advanced way. What if you had a large 
chart with 10 rows and 5 numbers in each row. Suppose you 
wanted to find the average of the five numbers in each row. You 
could create 10 arrays and have the computer calculate the 
average of the five numbers in each one. This is not necessary, 
because you can put all the numbers in a two-dimensional array. 
This array would have the same dimensions as the chart of 
numbers you want to work with—10 rows by 5 columns. The DIM 
statement for this array (we will call it array X) should be: 


10 DIM X(10,5) 


This tells the computer to reserve space in its memory for a two- 
dimensional array named X. The computer reserves enough 
space for 50 numbers. You do not have to fill an array with as 
many numbers as you DiMensioned it for, but the computer will 
still reserve enough space for all of the positions in the array. 


Sample Program 


Now it becomes very easy to refer to any number in the chart by 
its column and row position. Refer to the chart below. Find the 
third element in the tenth row (1500). You would refer to this 
number as X(10,3) in your program. The following program reads 
the numbers from the chart into a two-dimensional array (X) and 
calculates the average of the numbers in each row. 





Column 
1 
1 1 3 5 7 9 
2 2 4 6 8 10 
3 5 10 15 20 25 
4 10 20 30 40 50 
5 20 40 60 80 100 
6 30 60 90 120 150 
7 40 80 120 160 200 
8 50 100 150 200 250 
9 100 200 300 400 500 
10 500 1000 1500 2000 2500 


DIM X(10,5), A(1®0) 
FOR R=l TO 10 
T=0 
FOR C=l TO 5 
READ X(R,C) 
T=T+X (R,C) 
NEXT C 
A(R)=T/5 
NEXT R 
FOR R=l TO 19 
PRINT "ROW #";R 
FOR C=l TO 5 
PRINT X(R,C) 
NEXT C 


PRINT "AVERAGE =";A(R) 
FOR D=1 TO 1000:NEXT 


NEXT R 
DATA 1,3,5,7,9 

DATA 2,4,6,8,19 

DATA 5,10,15,28,25 

DATA 10,20,30,40,590 

DATA 20,40,60,88,190 

DATA 30,60,90,120,150 

DATA 40,80,120,160,200 

DATA 50,100,150,200,250 

DATA 100,200,300,400,500 
DATA 500,1000,1500,2000, 2500 
END 





PROGRAMMING SUBROUTINES 


The GOSUB-RETURN command 


Until now, the only method ou have had to tell the computer to 
jump to another part of your program is to use the GOTO 
command. What if you want the computer to jump to another part 
of the program, execute the statements in that section, then 
return to the point it left off and continue executing the program? 


The part of program that the computer jumps to and executes is 
called a subroutine. Clear your computer's memory and enter 
the program below. 


10 A$=““SUBROUTINE”:B$="“PROGRAM”’ 
20 FOR J=1 TO 5 

30 INPUT “ENTER A NUMBER’”’;X 

40 GOSUB 100 

50 PRINT B$:PRINT 

60 NEXT 

70 END 

100 PRINT A$:PRINT 

110 Z+Xt2:PRINT Z 

120 RETURN 


This program will square the numbers you type and print the 
result. The other print messages tell you when the computer is 
executing the subroutine or the main program. Line 40 tells the 
computer to jump to line 100, execute it and the statements 
following it until it sees a RETURN command. The RETURN 
statement tells the computer to go back in the program to the line 
immediately following the GOSUB command and continue 
executing. The subroutine can be anywhere in the program— 
including after the END statement. Also, remember that the 
GOSUB and RETURN commands must always be used together 
in a program (like FOR-NEXT and IF-THEN), otherwise the 
computer will give an error message. 


The ON GOTO/GOSUB command 


There is another way to make the computer jump to another 
section of your program (called branching). Using the ON 
statement, you can have the computer decide what part of the 
program to branch to based on a calculation or keyboard input. 


AnT 


The ON statement is used with either the GOTO or GOSUB- 
RETURN commands, depending on what you need the program 
to do. A variable or calculation should be after the ON command. 
After the GOTO or GOSUB commana, there should be a list of 
line numbers. Type in the program below to see how the ON 
command works. 


10 ?“ENTER A NUMBER BETWEEN ONE AND FIVE” 
20 INPUT X 

30 ON X GOSUB 100,200,300,400,500 

40 END 

100 ? “YOUR NUMBER WAS ONE”’:RETURN 

200 ? “YOUR NUMBER WAS TWO” :RETURN 

300 ? “YOUR NUMBER WAS THREE” :RETURN 

400 ? “YOUR NUMBER WAS FOUR”: RETURN 

500 ? “YOUR NUMBER WAS FIVE”’:RETURN 


When the value of X is 1, the computer branches to the first line 
number in the list (100). When X is 2, the computer branches to 
the second number in the list (200), and so on. 


USING MEMORY LOCATIONS 


Using PEEK and POKE for RAM/ROM access 


Each area of the computer's memory has a special function. For 
instance, there is a very large area to store your programs and 
the variables associated with them. This part of memory, called 
RAM, is cleared when you use the NEW command. Other areas 
are not as large, but they have very specialized functions. For 
instance, there is an area of memory locations that controls the 
music features of the computer. 


There are two BASIC commands—PEEK and POKE—that you 
can use to access and manipulate the computer's memory. Use 
of PEEK and POKE commands can be a powerful programming 
device because the contents of the computer’s memory locations 
determine exactly what the computer should be doing at a 
specific time. 
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Using PEEK 


PEEK can be used to make the computer tell you what value is 
being stored in a memory location (a memory location can store 
any value between 0 and 255). You can PEEK the value of any 
memory location (RAM or ROM) in DIRECT or PROGRAM mode. 
Type: 


P=PEEK(2594) aan 
?P =Tuae 


The computer assigns the value in memory location 2594 to the 
variable P when you press RETURN after the first line. Then it 
prints the value when you press RETURN after entering the ? P 
command. Memory location 2594 determines whether or not keys 
like the spacebar and CRSR repeat when you hold them down. A 
128 in location 2594 tells the computer to repeat these keys 
when you hold them down. Hold down the spacebar and watch 
the cursor move across the screen. 


Using POKE 


To change the value stored in a RAM location, use the POKE 
command. Type: 


POKE 2594,96 ER 


The computer stores the value after the comma (96) in the 
memory location before the comma (2594). A 96 in memory 
location 2594 tells the computer not to repeat keys like the 
spacebar and CRSR keys when you hold them down. Now hold 
down the spacebar and watch the cursor. The cursor moves one 
position to the right, but it does not repeat. To return your 
computer to its normal state, type: 


POKE 2594,128 3 35tun 


You cannot alter the value of all the memory locations in the 
computer—the values in ROM can be read, but not changed. 


NOTE: These examples assume you are in bank 0. See the 
description of the BANK command in Chapter V, BASIC 7.0 
Encyclopaedia for details on banks. 


BASIC FUNCTIONS 


What is a Function 


A function is a predefined operation of the BASIC language that 
generally provides you with a single value. When the function 
provides the value, it is said to “return” the value. For instance, 
the SQR (square) function is a mathematical function that returns 
the value of a specific number when it is raised to the second 
power—1.e., Squared. 


There are two kinds of functions: 


Numeric—returns a result which is a single number. 
Numeric functions range from calculating mathematical 
values to specifying the numeric value of a memory location. 


String—returns a result which is a character. 


Following are descriptions of some of the more commonly used 
functions. For a complete list of BASIC 7.0 functions see Chapter 
V, BASIC 7.0 Encyclopaedia. 


The INTEGER Function (INT) 


What if you want to round off a number to the nearest integer? 
You'll need to use INT, the integer function. The INT function 
takes away everything after the decimal point. Try typing these 
examples: 


7? iNT(4.25) RETURN 
2? INT(4.75) RETURN 
? INT(SQR(50)) RETURN 


If you want to round off to the nearest whole number, then the 
second example should return a value of 5. In fact, you should 
round up any number with a decimal above 0.5. To do this, you 
have to add 0.5 :o the number before using the INT function. In 
this way, numbers with decimal portions above 0.5 will be 
increased by 1 before being rounded down by the INT function. 
Try this: 


? INT(4.75+0.5) =r 


The computer added 0.5 to 4.75 before it executed the INT 
function, so that it rounded 5.25 down to 5 for the result. If you 
want to round off the result of a calculation, do this: 
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? INT((100/6)+0.5) =3tBRNE 


You can substitute any calculation for the division shown in the 
inner parentheses. 


What if you want to round off numbers to the nearest 0.01? 
Instead of adding 0.5 to your number, add 0.005, then multiply by 
100. Let’s say you want to round 2.876 to the nearest 0.01. Using 
this method, you start with: 


? (2.876 + 0.005)*100 =axerEiree 


Now use the INT function to get rid of everything after the 
decimal point (which moves two places to the right when you 
multiply by 100). You are left with: 


? INT((2.876 + 0.005)*100) HeTERRE 


which gives you a value of 288. All that’s left to do is divide by 
100 to get the value of 2.88, which is the answer you want. Using 
this technique, you can round off calculations like the following to 
the nearest 0.01: 


2 INT(((2.876+1.29+16.1 - 9.534)+0.005) 
*100)/100 ==uaRE 





Generating Random Numbers—The RND Function 


The RND functions tells the computer to generate a random 
number. This can be useful in simulating games of chance, and 
in creating interesting graphic or music programs. All random 
(RND) numbers are nine digits, in decimal form, between the 
values 0.000000001 and 0.999999999. Type: 


? RND (0) seen 


Multiplying the randomly generated number by six makes the 
range of generated numbers increase to greater than 0 and less 
than 6. In order to include 6 among the numbers generated, we 
add one to the result of RND(0)*6. This makes the range 1<X<7. 
If we use the INT function to eliminate the decimal places, the 
command will generate whole numbers from 1 to 6. This process 
Can be used to simulate the rolling of a die. Try this program: 


10 R= (INT(RND(1)*6+1) 
20 ?R 
30 GOTO 10 
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Each number generated represents one toss of a die. To simulate 
a pair of dice, use two commands of this nature. Each number is 
generated separately, and the sum of the two numbers 
represents the total of the dice. 


The ASC and CHR$ Functions 


Every character that the Commodore 128 can display (including 
graphic characters) has a number assigned to it. This number is 
called a character string code (CHR$) and there are 255 of them 
in the Commodore 128. There are two functions associated with 
this concept that are very useful. The first is the ASC function. 
Type: 


? ASC(“Q”) RETURN: 


The computer responds with 81. 81 is the character string code 
for the Q key. Substitute any key for Q in the command above to 
find out the Commodore ASCII code number for any character. 


The second function is the CHR$ function. Type: 
2?CHR$(81) RETURN 


The computer responds with Q. In effect, the CHR$ function is 
the opposite of the ASC function. They both refer to the table of 
character string codes in the computer's memory. CHR$ values 
can be used to program function keys. See Section 5 for more 
information about this use of CHR$. See Appendix E of this Guide 
for a listing of ASC and CHR$ codes. 


Converting Strings and Numbers 


Sometimes you may need to perform calculations on numeric 
Characters that are stored as string variables in your program. 
Other times, you may want to perform string operations on 
numbers. There are two BASIC functions you can use to convert 
your variables from numeric to string type and vice versa. 
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The VAL Function 
The VAL function returns a numeric value for a string argument. 
Clear the computer's memory and type in this program: 


10 A$="64” 

20 A=VAL(A$) 

30 ? “THE VALUE OF ”;A$;‘ IS”3A 
40 END 


The STR$ Function 


The STR$ function returns the string representation of a numeric 
value. Clear the computer's memory and type this program. 


10 A=65 

20 A$=STR$(A) 

30 ? A“ IS THE VALUE OF ”;A$ 
The Square Root Function (SQR) 


The square root function is SQR. For example, to find the square 
root of 50, type: 


? SQR(50) RETURN 
You can find the square root of any positive number in this way. 


The Absolute Value Function (ABS) 


The absolute value function (ABS) is very useful in dealing with 
negative numbers. You can use this function to get the positive 
value of any numberpositive or negative. Try these examples: 


? ABS(-10) RETURN 
? ABS(5) IS EQUAL TO ”ABS(-5) 43EfaRae 


THE STOP AND CONT (CONTINUE) COMMANDS 


You can make the computer stop a program, and resume running 
it when you are ready. The STOP command must be included in 
the program. You can put a STOP statement anywhere you want 
to ina program. When the computer ‘‘breaks” from the program 
(that is, stops running the program), you can use DIRECT mode 
commands to find out exactly what is going on in the program. 
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For example, you can find the value of a loop counter or other 
variable. This is a powerful device when you are “debugging” or 
fixing your program. Clear the computer's memory and type the 
program below. 


10 X=INT(SQR(630)) 

20 Y=(.025*80)12 

30 X=INT(X*Y) 

40 STOP 

50 FOR J=0 TO ZSTEP Y 

60 ? “STOP AND CONTINUE” 
70 NEXT 

80 END 


Now RUN the program. The computer responds with “BREAK IN 
40”. At this point, the computer has calculated the values of X, Y 
and Z. If you want to be able to figure out what the rest of the 
program is supposed to do, tell the computer to PRINT X;Y;Z. 
Often when you are debugging a large program (or a complex 
small one), you'll want to know the value of a variable at a certain 
point in the program. 


Once you have all the information you need, you can type CONT 
(for CONTinue) and press RETURN assuming you have not 
edited anything on the screen. The computer then CONTinues 
with the program, starting with the statement after the STOP 
command. 


KaKKKKKR KKK aK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


This section and the preceding one have been designed to 
familiarize you with the BASIC programming language and its 
capabilities. The remaining four sections of this chapter describe 
commands that are unique to Commodore 128 mode. Some 
Commodore 128 mode commands provide capabilities that are 
not available in C64 mode. Other Commodore 128 mode 
commands let you do the same things as a certain C64 
command, but more easily. The syntax for all Commodore 7.0 
commands is given in Chapter V, BASIC 7.0 Encyclopaedia. 
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INTRODUCTION 


This section introduces you to some powerful BASIC commands 
and statements that you probably have not seen before, even if 
you are an experienced BASIC programmer. If you are familiar 
with programming in BASIC, you have probably encountered 
many situations in which you could have used these commands 
and statements. This section explains the concepts behind each 
command and gives examples of how to use each command ina 
program. (A complete list and an explanation of these commands 
and statements may be found in Chapter V, BASIC 7.0 
Encyclopaedia.) This section also describes how to use the 
special keys that are available to you in C128 mode. 


ADVANCED LOOPING 


DO/LOOP statement 


The DO/LOOP statement provides more sophisticated ways to 
create a loop than do the GOTO, GOSUB or FOR/NEXT 
statements. The DO/LOOP statement combination brings to the 
BASIC language a very powerful and versatile technique normally 
available only in structured programming languages. We discuss 
just a few possible uses of DO/LOOP in this explanation. 


If you want to create an infinite loop, you start with a DO 
statement, then enter the line or lines that specify the action you 
want the computer to perform. Then end with a LOOP statement 
like this: 


100 DO 
110 PRINT “REPETITION” 
120 LOOP 


Press the RUN/STOP key to stop the program. 

The directions following the DO statement are carried out until 
the program reaches the LOOP statement (line 120); control is 
then transferred back to the DO statement, (line 100). Thus any 
statements in between DO and LOOP are performed indefinitely. 
UNTIL 


Another useful technique is to combine the DO/LOOP with the 
UNTIL statement. The UNTIL statement sets up a condition that 
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directs the loop. The loop will run continually unless the condition 
for UNTIL happens. 


100 DO: INPUT ‘DO YOU LIKE YOUR COMPUTER” ;A$ 
110 LOOP UNTIL A$=“YES” 
120 PRINT “THANK YOU” 


The DO/LOOP statement is often used to repeat an entire 
routine indefinitely in the body of a program, as in the following: 


10 PRINT “PROGRAM CONTINUES UNTIL YOU TYPE 
‘QUIT’” 

20 DO UNTIL A$="‘QUIT” 

30 INPUT “DEGREES FAHRENHEIT”’;F 

40 C=(5/9)*(F-32) 

50 PRINT F;‘* DEGREES FAHRENHEIT EQUALS “‘C; “ 
DEGREES CELSIUS” 

60 INPUT “AGAIN OR QUIT”;A$ 

70 LOOP 

80 END 


Another use of DO/LOOP is as a counter, where the UNTIL 
statement is used to specify a certain number of repetitions. 


10 N=2*2 

20 PRINT“TWO DOUBLED EQUALS”; N 
30 DO UNTIL X=25 

40 X=X+1 

50 N=N*2 

60 PRINT“DOUBLED”’;X+1;“TIMES...”;N 
70 LOOP 

80 END 


Notice that if you leave the counter statement out (the UNTIL 
X=25 part in line 30), the number is doubled indefinitely until an 
OVERFLOW error occurs. 


WHILE 


The WHILE statement works in a similar way to UNTIL, but the 
loop is repeated only while the condition is in effect, such as in 
this reworking of the last brief program: 


100 DO: INPUT “DO YOU LIKE YOUR COMPUTER” ;A$ 
110 LOOP WHILE A$ < > “YES” 
120 PRINT “THANK YOU” 
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EXIT 


An EXIT statement can be placed within the body of aDO/LOOP. 
When the EXIT statement is encountered, the program jumps to 
the next statement following the LOOP statement. 


The ELSE clause with IF-THEN 


The ELSE clause provides a way to tell the computer how to 
respond if the condition of the IF-THEN statement is false. Rather 
than continuing to the next program line, the computer will 
execute the command or branch to the program line mentioned 
in the ELSE clause. For example, if you wanted the computer to 
print the square of a number, you Could use the ELSE clause like 
this: 

10 INPUT “TYPE A NUMBER TO BE SQUARED”’;N 

20 IF N< 100 THEN PRINT N*N: ELSE 40 

30 END 

40 ?‘“‘NUMBER MUST BE < 100”: GOTO 10 


Notice that you must use a colon between the IF-THEN 
statement and the ELSE clause. 


The BEGIN/BEND Sequence with IF-THEN 


BASIC 7.0 allows you to take the IF-THEN condition one step 
further. The BEGIN/BEND sequence permits you to include a 
number of program lines to be executed if the IF condition is true, 
rather than one simple action or GOTO. The command is 
constructed like this: 


IF condition THEN BEGIN: 
(program lines): 
BEND:ELSE 


Be sure to place a colon between BEGIN and any instructions to 
the computer, and again between the last command in the 
sequence and the word BEND. BEGIN/BEND can be used 
without an ELSE clause, or can be used following the ELSE 
clause when only a single command follows THEN. Try this 
program: 
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10 INPUT A 

20 IF A< 100 THEN BEGIN: ? “YOUR NUMBER WAS ”;A 
30 SLEEP 2:REM DELAY 

40 FOR X=1TOA 

50 ?‘‘THIS IS AN EXAMPLE OF BEGIN/BEND” 

60 NEXT X 

70 ?“THAT’S ENOUGH”: BEND:ELSE ?‘‘TOO MANY” 

80 END 


This program asks for a number from the user. IF the number is 
less than 100, the statements between the keywords BEGIN and 
BEND are performed, along with any statements on the same line 
as BEND (except for ELSE). The message “YOUR NUMBER 
WAS N” appears on the screen. Line 30 is a delay used to keep 
the message on the screen long enough so it can be read easily. 
Then a FOR/NEXT loop is used to display a message the 
number of times specified by the user. If the number is greater 
than 100, the THEN condition is skipped, and the ELSE condition 
(printing “TOO MANY”) is carried out. The ELSE keyword must 
be on the same line as BEND. 


The SLEEP Command 


Note the use of the SLEEP command in line 30 of the program 
just discussed. SLEEP provides an easier, more accurate way of 
inserting and timing a delay in program operation. The format for 
the SLEEP command is 


SLEEP n 


where n indicates the number of seconds, in the range 0 to 
65535, that you want the program to delay. In the command 
shown in line 30, the 2 specifies a delay of two seconds. 


FORMATTING OUTPUT 


The PRINT USING Command 


Suppose you were writing a sales program that calculated a 
dollar amount. Total sales divided by number of salespeople 
equals average sales. But performing this calculation might result 
in dollar amounts with four or five decimal places! You can format 
the results the computer prints so that only two decimal places 
are displayed. The command which performs this function is 
PRINT USING. 
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PRINT USING lets you create a format for your output, using 
Spaces, commas, decimal points and dollar signs. Hash marks 
(the # sign) are used to represent spaces or characters in the 
displayed result. For example: 


PRINT USING “#S###HH##H.H#H’A 


tells the computer that when A is printed, it should be in the form 
given, with up to six places to the left of the decimal point, and 
two places to the right. The hash mark in front of the dollar sign 
indicates that the $ should float, that is, it should always be 
placed next to the left-most number in the format. 


If you want a comma to appear before the last three dollar 
places, as in $1,000.00 include the comma in the PRINT USING 
statement. Remember you can format output with spaces, 
commas, decimal points, and dollar signs. There are several 
other special characters for PRINT USING, see the BASIC 
Encyclopaedia for more information. 


The PUDEF Command 


If you want formatted output representing something other than 
dollars and cents, use the PUDEF (Print Using DEFine) 
command. You can replace any of four format characters with 
any character on the keyboard. 


The PUDEF command has four positions, but you do not have to 
redefine all four. The command looks like this: 


PUDEF“ ,.$” 
V2 34 

Here: 

® position 1 is the filler character. A blank will appear if you 

do not redefine this position. 

® position 2 is the comma character. Default is the comma. 

® position 3 is the decimal point. 

® position 4 is the dollar sign. 
lf you wrote a program that converted dollar amount to English 
pounds, you could format the output with these commands: 


10 PUDEF “,.£” 
20 PRINT USING “#$#### ##”;X 
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SAMPLE PROGRAM 


This program calculates interest and loan payments, using some 
of the commands and statements you just learned. It sets a 
minimum value for the loan using the ELSE clause with an |F- 
THEN statement, and sets up a dollar and cents format with 
PRINT USING. 


10 INPUT “LOAN AMOUNT IN DOLLARS”;A 

20 IF A< 100 THEN 70: ELSE P=.15 

30 I=A*P 

40 ?“TOTAL PAYMENT EQUALS”; 

50 PRINT USING “#SH###H#H.##” A+ 

60 GOTO 80 

70 ?“LOANS OF UNDER $100 NOT AVAILABLE’”’ 
80 END 


INPUTTING DATA WITH THE GETKEY COMMAND 


You have learned to use INPUT and GET commands to enter 
DATA during a program. Another way for you to enter data while 
a program is being RUN is with the GETKEY statement. The 
GETKEY statement accepts only one key at a time. GETKEY is 
usually followed by a string variable (A$ for example). Any key 
that is pressed Is assigned to that string variable. GETKEY is 
useful because it allows you to enter data one character at a time 
without having to press the RETURN key after each character. 
The GETKEY statement may only be used in a program. 


Here is an example of using GETKEY in a program. 


1000 PRINT “PLEASE CHOOSE A, B, C, D, E, OR F” 
1010 GETKEY A$ 
1020 PRINT A$;‘“‘ WAS THE KEY YOU PRESSED.” 


The computer waits until a single key is pressed; when the key Is 
pressed, the character is assigned to variable A$, and printed out 
in line 1020. The following program features GETKEY in more 
complex and useful fashions: for answering a multiple-choice 
question and also asking if the question should be repeated. If the 
answer given Is incorrect, the user has the option to try again by 
pressing the “Y” key (line 80). The key pressed for the multiple 
choice answer is assigned to variable A$ while the “TRY AGAIN” 
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answer is assigned to B$, through the GETKEY statements in 
lines 60 and 90. IF/THEN statements are used for loops in the 
program to get the proper computer reaction to the different 
keyboard inputs. 


10 PRINT “WHO WROTE ‘THE RAVEN’?” 

20 PRINT “A. EDGAR ELLEN POE” 

30 PRINT “B. EDGAR ALLEN POE’”’ 

40 PRINT “C. IGOR ALLEN POE” 

50 PRINT “D. ROB RAVEN” 

60 GETKEY A$ 

70 IF A$=“‘B” THEN 150 

80 PRINT “WRONG. TRY AGAIN? (Y OR N)” 

90 GETKEY B$ 

100 IF B$=“‘Y” THEN PRINT “A,B,C, OR D?”:GOTO 60 
110 IF B$=‘N” THEN 140 

120 PRINT “TYPE EITHER Y OR N - TRY AGAIN” 
130 GOTO 90 

140 PRINT “THE CORRECT ANSWER IS B.” 

145 GOTO 160 

150 PRINT “CORRECT!” 

160 END 


GETKEY is very similar to GET, except GETKEY will wait for a 
key to be pressed. 


PROGRAMMING AIDS 


In earlier sections you learned how to make changes in your 
programs, and correct typing mistakes with INST/DEL. BASIC 
also provides other commands and functions which help you 
locate actual program errors, and commands which you can use 
to make programming sessions flow more smoothly. 


Entering Programs 


Auto 

C128 BASIC provides an auto-numbering process. You 
determine the increment for the line numbers. Say you want to 
number your program in the usual manner, by tens. Before you 
begin to program, while in DIRECT mode, type: 


AUTO 10 RETURN 
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The computer automatically numbers your program by tens. After 
you enter a line and press the RETURN key, the next line number 
appears, and the cursor is in the correct place for you to type the 
next statement. You can choose to have the computer number 
the commands with any increment; you might choose 5 or even 
50. Just place the number after the word AUTO and press 
RETURN. To turn off the auto-numbering feature, type AUTO with 
no increment, and press RETURN. 


Renumber 

If you write a program and later add statements to It, sometimes 
the line numbering can be awkward. Using the RENUMBER 
command you can change the line numbers to an even 
increment for part or all of your program. The RENUMBER 
command has several optional parameters, as listed below in 
brackets: 


RENUMBER [ [new starting line] [,[increment] 
increment] [,old starting line]]] | ] 


The new starting line is what the first program line will be 
numbered after the RENUMBER command is used. If you do not 
specify, the default is 10. The increment is the spacing between 
line numbers, and it also defaults to 10. The old starting line 
number is the line number where renumbering Is to begin. This 
feature allows you to renumber a portion of your program, rather 
than ail of it. It defaults to the first line of the program. For 
example, 


RENUMBER 40,,80 
tells the computer to renumber the program starting at line 80, in 
increments of 10. Line 80 becomes line 40. 


Notice that this command, like AUTO, can only be executed in 
DIRECT mode. 


Delete 

You know how to delete program lines by typing the line number 
and pressing the RETURN key. This can be tedious If you want to 
erase an entire portion of your program. The DELETE command 
Can save you time because you can specify a range of program 
lines to erase all at once. For example, 


DELETE 10-50 
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will erase lines 10, 50, and any in between. The use of DELETE is 
similar to that of LIST, in that you can specify a range of lines up 
to a given line, or following it, or a single line only, as in these 
examples: 


DELETE—120 

erases all lines up to and including 120 
DELETE 120— 

erases line 120 and any line after it 
DELETE 120 

erases line 120 only 


Identifying Problems in Your Programs 


When a program does not work the way you expected, an error 
message usually occurs. Sometimes the messages are vague, 
however, and you still do not understand the problem. The 
Commodore 128 computer has several ways of helping you 
locate the problem. 


Help 


The Commodore 128 provides a HELP command that specifies 
the line in which a problem has occurred. To actuate the HELP 
command, just press the special HELP key on the row of keys 
located above the main keyboard. 


Type the following statement. It contains an intentional error, so 
type it just as is: 


10 73;4:5;6 


When you RUN this one-line program, the computer prints 3 and 
4 as expected, but then responds “SYNTAX ERROR IN 10”. 
Suppose you cannot see the error (a colon instead of a semi- 
colon between 4 and 5). You press the HELP key. (You can also 
type HELP and press RETURN.) The computer displays the line 
again, but the 5:6 is high lighted to show the error is in that line. 


Error Trapping—The TRAP Command 


Usually, if an error occurs in a program, the program ‘‘crashes” 
(stops running). At that point, you can press the HELP key to 
track down the error. However, you can use the BASIC 7.0 TRAP 
command to include an error-trapping capability within your 


program. The TRAP command advises you to locate and correct 
an error, then resume program operation. Usually, the error- 
trapping function is set in the first line of a program: 


5 TRAP 100 


tells the computer that if an error occurs to go to a certain line (in 
this case, line 100). Line 100 appears at the end of the program, 
and sets up a contingency. Neither line is executed UNLESS 
there is an error. When an error occurs, the line with the TRAP 
statement is enacted, and control is directed to another part of 
the program. You can use these statements to catch anticipated 
errors in entering data, resume execution, or return to text mode 
from a graphics mode, to name just a few options. If you run the 
last DO/LOOP example (which doubled numbers) without an 
UNTIL statement, you can get an OVERFLOW error and the 
program crashes. You can prevent that from happening by 
adding two lines, one at the beginning of the program and one at 
the end. For this example, you might add these two lines: 


5 TRAP 100 
100 IF N>1 THEN END 


Even though N has been much greater than one for the entire 
program, the statement is not considered until there is an error. 
When the number “overflows” (is greater than the computer can 
accept), the TRAP statement goes into effect. Since N is greater 
than one, the program is directed to END (rather than crashing.) 


Here is an example in which trapping is used to prevent a zero 
from being input for division. 


10 TRAP 1000 

100 INPUT “I CAN DIVIDE BY ANY NUMBER. GIVE ME A 
NUMBER TO DIVIDE”’;D 

110 INPUT “WHAT SHOULD | DIVIDE IT BY”;B 

120 A=D/B 

130 PRINT D;“DIVIDED BY”;B;“EQUALS”;A 

140 END 

1000 IF B=0 THEN PRINT“EVEN | CAN’T DO THAT” 
1100 INPUT “PICK A DIFFERENT NUMBER’”B: 
RESUME 120 


Notice the RESUME in line 1100. This tells the computer to return 
to the line mentioned (in this case, 120) and continue. Depending 
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on the error that was trapped, resuming execution may or may 
not be possible. 


For additional information on error trapping, see the error 
functions ERR$, EL and ER, described in Chapter V, BASIC 7.0 
Encyclopaedia. 


Program Tracing—TRON and TROFF Commands 


When a problem in a program occurs, or you do not get the 
results you expect, it can be useful to methodically work through 
the program and do exactly what the computer would do. This 
process is Called tracing. Draw variable boxes and update the 
values according to the program statements. Perform 
calculations and print results following each instruction. 


Tracing may show you, for example, that you have used a GOTO 
with an incorrect line number, or calculated a result but never 
stored it in a variable. Many program errors can be located by 
pretending to be the computer, and following only one instruction 
at a time. Your C128 can perform a type of trace using the 
special commands TRON and TROFF (short for TRace ON and 
TRace OFF). When the program is run, with TRACE ON the 
computer prints the line numbers in the order they are executed. 
In this way, you may be able to see why your program is not 
giving the results you expected. 


Type any short program we have used so far, or use one of your 
own design. To activate trace mode, type TRON in DIRECT 
mode. When you run the program, notice how line numbers 
appear in brackets before any results are displayed. Try to follow 
the line numbers and see how many steps the computer needed 
to arrive at a certain point. TRON will be more interesting if you 
pick a program with many branches, such as GOTO, GOSUB 
and IF-THEN-line number. Type TROFF to turn trace mode off 
before continuing. 


You do not have to trace an entire program. You can place 
TRON within a program as a line prior to the program section 
causing problems. Put the word TROFF as a program line after 
the troublesome section. When you run the program, only the 
lines between TRON and TROFF will be bracketed in the results. 
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WINDOWING 


Windows are a specific area of the screen that you define as your 
workspace. Everything you type (lines you type, listings of 
programs, etc.) after setting a window, appears within the 
window's boundaries, not affecting the screen outside the window 
area. The Commodore 128 provides two methods of creating 
windows: the WINDOW command and ESCAPE key functions. 


Using the WINDOW Command to Create a Window 


The Commodore 128 BASIC 7.0 language features a command 
that allows you to create and manipulate windows: the WINDOW 
command. The command format Is: 


WINDOW top-left column, top-left row, bottom-right 
column, bottom-right row [,clear option] 


The first two numbers after WINDOW specify the column and row 
number of where you want the top left corner of the window to be; 
the next two numbers are the coordinates for the bottom right 
corner. Remember that the screen format (40 or 80 columns) 
dictates the acceptable range of these coordinates. You can also 
include a clear option with this command. If you add 1 onto the 
end of the command, the window screen area is cleared, as in 
this example: 


WINDOW 10,10,20,20,1 


SCNCLR:COLOR 5,5 :REM CLEAR SCREEN & SELECT PURPLE TEXT. 
COLORS5,5 
WINDOWG,@,39,24 :REM SET WINDOW TO FULL SCREEN 
COLOR @,13:COLOR 4,13 :REM SET 48 SCREEN TO MED GREY. 
AS="ABCDEFGHIJKLMNOPQRST" 
COLOR 5,5 ‘REM SELECT PURPLE TEXT, 
FORI=1 TO 25 sREM FILL SCREEN WITH CHARACTERS. 
PRINT AS;AS:NEXT I 
WINDOW 1,1,7,20 :REM DEFINE WINDOW 1. 
COLOR 5,3 :REM PRINT AS IN REVERSE RED TEXT. 
PRINT CHRS (18) ;AS; 
WINDOW 15,15,39,20,1 :REM DEFINE SECOND WINDOW. 
COLOR 5,7 :REM PRINT AS IN CYAN TEXT. 
FOR I=l TO 6:PRINT AS;:NEXT I 
WINDOW 30,1,39,22,1 :REM DEFINE THIRD WINDOW. 
COLOR 5,8:LIST :REM LIST IN YELLOW TEXT. 
WINDOW 5,5,33,18,1 :REM DEFINE FOURTH WINDOW. 
COLOR 5,2 :REM PRINT AS AND LIST IN WHITE TEXT. 
PRINT AS:LIST 
END 





Here is a sample program that creates four windows on the 
screen, in either 40- or 80-column format. 


Using the ESC Key to Create a Window 
To set a window with the ESC (Escape) Key, follow these steps: 


1. Move the cursor to the screen position you want as the 
top left corner of the window. 


2. Press the ESC key and release it, and then 
press T. 


3. Move the cursor to the position you want to be the bottom 
right corner of the window. 


4. Press ESC and release, then B. Your window 
iS now set. 


You can manipulate the window and the text inside using the 
ESC key. Screen editing functions, such as inserting and deleting 
text, scrolling, and changing the size of the window, can be 
performed by pressing ESC followed by another key. To use a 
specific function, press ESC and release it. Then press any of the 
following keys listed for the desired function: 


@ Erase everything from cursor to end of screen window 

A Automatic insert mode 

B Set the bottom right corner of the screen window (at the 
current cursor location) 

C Cancel automatic insert mode 

D Delete current line 

E Set cursor to non-flashing mode 

F Set cursor to flashing mode 

G Enable bell (by Control-G) 

H Disable bell 

| Insert a line 

J Move to the beginning of the current line 

K Move to the end of the current line 

L Turn on scrolling 

M Turn off scrolling 

N Return to normal (non-reverse video) screen display (80- 
column only) 

O Cancel insert and quote modes 

P Erase everything from beginning of line to the cursor 
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Q Erase everything from the cursor to the end of the line 

R Reverse screen display (80-column only) 

S Change to block cursor (@) 

T Set the top left corner of the screen window (at the 
Current cursor location) 

U Change to underline cursor (_) 

V Scroll screen up one line 

W Scroll screen down one line 

X Toggles between 40 and 80 columns 

Y Restore Default TAB stops 

Z Clear All TAB stops 


Experiment with the ESCape key functions. You will probably find 
certain functions more useful than others. Note that you can use 
the usual INST/DEL key to perform text editing inside a window 
as well. 


When a window is set up, all screen output is confined to the 
“box” you have defined. If you want to clear the window area, 
press SHIFT and CLEAR/HOME together. To cancel the window, 
press the CLEAR/HOME key twice. The window is then erased, 
and the cursor is positioned in the top left corner of the screen. 
Windows are particularly useful in writing, listing and running 
programs because they allow you to work in one area of the 
screen while the rest of the screen stays as Is. 


2 MHz OPERATION 


The FAST and SLOW Commands 


The 2 MHz operating mode allows you to run non-graphic 
programs in 80-column format at twice the normal speed. You 
can switch normal and fast operation by using the FAST and 
SLOW commands. 


The FAST command places the Commodore in 2 MHz mode. The 
format of this command is: 
FAST 


The SLOW command returns the Commodore 128 to 1 MHz 
mode. The format of this command is: 


SLOW 
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KEYS UNIQUE TO C128 MODE 


Function Keys 


The four keys on the Commodore 128 keyboard on the right side 
above the numeric keypad are special function keys that let you 
save time by performing repetitive tasks with the stroke of just 
one key. The first key reads F1/F2, the second F3/F4, the third 
F5/F6, and the last F7/F8. You can use functions 1, 3,5 and 7 
by pressing the key by itself. To use function keys 2, 4, 6, and 8, 
press SHIFT and the function key. 


Here are the standard functions for each key: 


FA F2 F3 F4 
GRAPHIC DLOAD“ DIRECTORY  SCNCLR 
F5 F6 F7 F8 
DSAVE“ RUN LIST MONITOR 


Here is what each function involves: 


KEY 1 enters one of the GRAPHICs modes when you 
supply the number of the graphics area and press 
RETURN. The GRAPHICs command Is necessary for 
giving graphics commands such as CIRCLE or 
PAINT. For more on GRAPHICs see Section 6. 

KEY 2 prints DLOAD” on the screen. All you do is enter the 
program name and hit RETURN to load a program 
from disk, instead of typing out DLOAD yourself. 

KEY 3 lists a DIRECTORY of files on the disk in the disk 
drive. 

KEY 4 clears the screen using the SCNCLR command. 

KEY 5 prints DSAVE” on the screen. All you do is enter the 
program name, and press RETURN to save the 
Current program on disk. 

KEY 6 RUNSs the current program. 

KEY 7 displays a LISTing of the current program. 

KEY 8 lets you enter the Machine Language Monitor. See 
Appendix J for a description of the Monitor. 


Redefining Function Keys 


You can redefine or program any of these keys to perform a 
function that suits your needs. Redefining is easy, using the KEY 
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command. You can redefine the keys from BASIC programs, or 
change them at any time in direct mode. A situation where you 
might want to redefine a function key is when you use a 
command frequently, and want to save time instead of repeatedly 
typing in the command. The new definitions are erased when you 
turn off your computer. You can redefine any of the function keys 
and as many times as you want. 


If you want to reprogram the F7 function key to return you to text 
mode from high-resolution or multicolor-graphic modes, for 
example, you would use the key command in this fashion: 


KEY 7,“‘GRAPHIC 0” + CHR$(13) 


CHR§$(13) is the ASCII code character for RETURN. So when you 
press the F7 key after redefining the key, what happens is the 
command “GRAPHIC 0” is automatically typed out and entered 
into the computer with RETURN. Entire commands or series of 
commands may be assigned to a function key. 


Other keys used in C128 Mode only 


Help 


As noted previously, when you make an error in a program, your 
computer displays an error message to tell you what you did 
wrong. These error messages are further explained in Appendix 
A of this manual. You can get more assistance with errors by 
using the HELP key. After an error message, press the HELP key 
to locate the exact point where the error occurred. When you 
press HELP, the line with the error is highlighted on the screen in 
reverse video (in 40 column) or underlined (in 80 column output). 
For example: 


?SYNTAX ERROR IN LINE 10 Your computer displays this. 
HELP You press HELP. 


10 PRONT ‘COMMODORE COMPUTERS” The line with the 
mistake is high lighted in reverse if in 40 column output or under 
lined in 80 column output. 


No Scroll 


Press this key down to stop the text from scrolling when the 
cursor reaches the bottom of the screen. This turns off scrolling 
until you press the NO SCROLL key again. 


Caps Lock 


This key lets you type in all capital letters without using the SHIFT 
key. The CAPS LOCK key locks in when you press it, and must 
be pressed again to be released. Caps lock only affects the 
lettered keys. 


40/80 Display 


The 40/80 key selects the main (default) screen format: either 40 
or 80 column. The selected screen displays all messages and 
output at power-up, or when RESET, or RUN/STOP/RESTORE 
are used. This key may be used to set the display format only 
before turning on or resetting the computer. You cannot change 
modes with this key after the computer is turned on unless you 
use RUN/STOP/RESET or RUN/STOP/RESTORE. Section 8 
provides an explanation of 40/80 column modes. 


Alt 
The ALT allows programs to assign a special meaning to a given 
key or set of keys. 


Unless a specific application program redefines it, holding down 
the ALT key and any other key has no effect. 
Tab 


This key works like the TAB key on a typewriter. It may be used 
to set or clear tab stops on the screen and to move the cursor to 
the columns where tabs are Set. 


Line Feed 


Pressing this key advances the cursor to the next line, similar to a 
cursor down key. 


KR REKKKEKEKKKEK KEK KEKKRKEKRKR KEKE KRKEKKKEKEKEKEKEKEKEKEKKKKKKKEKEKEKEKE 


FOR MORE INFORMATION 


This section covers only some of the concepts, keys and 
commands that make the Commodore 128 a special machine. 
You can find further explanations of the BASIC language in the 
BASIC 7.0 Encyclopaedia in Chapter V. 
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GRAPHICS OVERVIEW 


In C128 mode, the Commodore 128 BASIC 7.0 language 
provides many new and powerful commands and statements that 
make graphics programming much easier. Each of the two 
screen formats available in C128 mode (40 columns and 80 
columns) is controlled by a separate microprocessor chip. The 
40-column chip is called the Video Interface Controller, or VIC for 
short. The 80-column chip is referred to as the 8563. The vic 
chip, which provides 16 colors, controls all the highly detailed 
graphics called bit-mapped graphics. The 80-column chip, which 
also offers 16 colors, only displays characters and character 
graphics. Thus, all detailed graphic programs in C128 mode must 
be done in 40-column format. 


Graphic Features 


As part of its impressive C128 mode graphics capabilities, the 
Commodore 128 provides: 


@ 13 specialized graphics commands 

@ 16 colors 

@ Six different display modes 

@ Eight programmable movable objects called SPRITES 
@ Combined graphics/text displays 


All these features can be integrated to provide a versatile, easy to 
use graphics system. 

Command Summary 

Here is a brief explanation of each graphic command: 


BOX — Draws rectangles on the bit map screen 

CHAR -— Displays characters on the bit map screen 

CIRCLE — Draws circles, ellipses and other geometric 
shapes 

COLOR — Selects colors for screen border, foreground, 


background and characters 
6-3 


DRAW — Displays lines and points on the bit map 
screen 

GRAPHIC— Selects a screen display (text, bit map or split 
screen bit map) 


PAINT — Fills area on the bit-map screen with color 

SCALE — Sets the relative size of the images on the bit- 
map screen 

SPRDEF — Enters sprite definition mode to edit sprites 

SPRITE — Enables, colors, sets sprite screen priorities, 


and expands a Sprite 

SPRSAV — Stores a text string variable into a sprite 
storage area and vice versa 

SSHAPE — Stores the image of a portion of the bit map 
screen into a text string variable 


Most of these commands are described in the examples in this 
section. See Chapter V, BASIC 7.0 Encyclopaedia, for detailed 

format and information on all graphic commands and functions, 
including those not discussed in this section. 


GRAPHICS PROGRAMMING ON THE C128 


This following section describes a step-by-step graphics 
programming example. As you learn each graphics command, 
add it to a program you will build as you read this section. When 
you are finished, you will have a complete graphics program. 


Choosing Colors 


The first step in graphics programming is to choose colors for the 
screen background, foreground and border. To select colors, 
type: 

COLOR source, color 


where source is the section of the screen you are coloring 
(background, foreground, border etc.) and color is the color code 
for the source. See Figure 6-1 for source numbers, Figure 6-2 for 
40-column-format color numbers, and Figure 6-3 for 80-column- 
format color numbers. 
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Number Source 


0 40-column background color (VIC) 
1 Foreground for the graphics screen (VIC) 
2 Foreground color 1 for the multicolor screen (VIC) 
3 Foreground color 2 for the multicolor screen (VIC) 
4 40-column (VIC) border (whether in text or graphics 
mode) 
S. Character color for 40- or 80-column text screen 
6 80-column background color (8563) 
Figure 6-1. Source Numbers 
Color Code Color Color Code Color 
1 Black 9g Orange 
2 White 10 Brown 
3 Red 11 Light Red 
4 Cyan 12 Dark Gray 
S, Purple 13 Medium Gray 
6 Green 14 Light Green 
7 Blue 15 Light Blue 
8 Yellow 16 Light Gray 
Figure 6-2. Color Numbers in 40-Column Format 
Color Code Color Color Code Color 
1 Black 9 Dark Purple 
2 White 10 Brown 
3 Dark Red 11 Light Red 
4 Light Cyan 12 Dark Cyan 
5 Light Purple 13 Medium Gray 
6 Dark Green 14 Light Green 
if Dark Blue 15 Light Blue 
8 Light Yellow 16 Light Gray 


Figure 6-3. Color Numbers in 80-Column Format 


Types of Screen Display 


Your C128 has several different ways of displaying information on 
the screen; the parameter “source” in the COLOR command 
pertains to different modes of screen display. The types of video 
display fall into three categories. 
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The first one is text display, which displays only characters, such 
as letters, numbers, special symbols and the graphics characters 
on the front faces of most C128 keys. The C128 can display text 
in both 40-column and 80-column screen formats. 


The second category of display mode is used for highly detailed 
graphics, such as pictures and intricate drawings. This type of 
display mode includes standard bit-map mode and multicolor bit- 
map mode. Bit-map modes allow you to control each and every 
individual screen dot or pixel (picture element). This allows 
considerable detail in drawing pictures and other computer art. 
The 80 column display is intended to display text. 


The difference between text and bit map modes lies in the way in 
which each screen addresses and stores information. The text 
screen can only manipulate entire characters, each of which 
covers an area of 8 by 8 pixels on your screen. The more 
powerful bit-map mode exercises control over each and every 
pixel on your screen. 


The third type of screen display, split screen, is a mixture of the 
first two types. The split screen display outputs part of the screen 
as text and part in bit map mode (either standard or multicolor). 
The C128 Is capable of this because It uses two separate and 
different parts of the computer's memory to store the two 
screens: one part for the text, and the other for the graphics 
screen. 


Type the following short program: 


10 COLOR 0,1: REM TEXT BACKGROUND COLOR = 
BLACK 

20 COLOR 1,3: REM FOREGROUND COLOR FOR BIT 
MAP SCREEN = RED 

30 COLOR 4,1: REM BORDER COLOR = BLACK 


This example colors the background black, the foreground red 
and the border black. 
Selecting the Graphic Mode 


The next graphics programming step is to select the appropriate 
graphic mode. This is done using the GRAPHIC command, 
whose format is as follows: 
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GRAPHIC <mode [,c] [,s] / CLR> 


where mode is a digit between 0 and 5, cis eitheraQor1 ands 
is a value between 0 and 25. Figure 6-4 shows the values 
corresponding to the graphic modes. 


Mode Description 


0 40-column standard text 
Standard bit map 

Standard bit map (split screen) 
Multicolor bit map 

Multicolor bit map (split screen) 
80-column text 


Of ONM — 


Figure 6-4. Graphic Modes 


The parameter CLR stands for CLEAR. Figure 6-5 explains the 
values associated with CLEAR. 


C Value Description 
0 Do not clear the graphics screen 
1 Clear the graphics screen 


Figure 6-5. CLEAR Parameters 


When you first run your program, you will want to clear the 
graphics screen for the first time, So set c equal to 1 in the 
GRAPHIC command. If you run it a second time, you may want to 
leave your picture on the screen, instead of drawing it all over 
again. In this case, set c equal to 0. 


The s parameter specifies where the start of the text screen in 
split screen mode Is to begin at the line after the specified line 
number. lf you omit the s parameter and select a split-screen 
graphic mode (2 or 4), the text screen portion is displayed in rows 
20 through 25; the rest of the screen is bit mapped. The s 
parameter allows you to change the starting line of the text 
screen to any line on the screen, ranging from 1 through 25. A 
zero as the s parameter indicates the screen is not split, and Is all 
text. 


The final GRAPHIC command parameter is CLR. When you first 
issue a bit map graphic command, the Commodore 128 allocates 
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a 9K area for your bit-mapped screen information. 8K is reserved 
for the data for your bit map and the additional 1K is dedicated for 
the color data (video matrix). Since 9K is a substantial block of 
memory, you may want to use it again for another purpose later 
on in your program. This is the purpose of CLR. It reorganizes the 
Commodore 128 memory and gives you back the 9K of memory 
that was dedicated to the bit map-screen, so you can use it for 
other purposes. 


The format for CLR is as follows: 
GRAPHIC CLR 


When using this format, omit all other GRAPHIC command 
parameters. 


Add the following command to your program. It places the C128 
in standard bit-map mode and allocates an 8K bit-map screen 
(and 1K of color data) for you to create graphics. 


40 GRAPHIC 1,1 


The second 1 in this command clears the bit map screen. If you 
do not want to clear the screen, change the second 1 to 0 (or 
omit it completely). 


NOTE: If you are in bit-map mode and are unable to return 
to the text screen, press the RUN/STOP and RESTORE 
keys at the same time, or press the ESC key followed by X, 
to return to the 80-column screen. Even though you can only 
display graphics with the VIC (40 column) chip, you can still 
write graphics programs in 80-column format. If you have 
the Commodore 1901 dual monitor and you want to view 
your graphics program while it is running, you must select 
the 40-column output by switching the slide switch on the 
monitor to 40-column output. 


Displaying Graphics on the Screen 


So far, you have selected a graphics mode and the colors you 
want. Now you can start displaying graphics on the screen. Start 
with a circle. 


Drawing a Circle — The CIRCLE command 
To draw a circle, use the CIRCLE statement as follows: 
60 CIRCLE 1,160,100,40,40 


This displays a circle in the center of the screen. The CIRCLE 
statement has nine parameters you can select to achieve various 
types of circles and geometric shapes. For example, by changing 
the numbers in the CIRCLE statement in line 60 you can obtain 
different size circles or variations in the shape (e.g., an oval). The 
CIRCLE statement adds power and versatility in programming 
Commodore 128 graphics in BASIC. The meaning of the 
numbers in the CIRCLE statement is explained under the CIRCLE 
listing in Chapter V, BASIC 7.0 Encyclopaedia. 


On your Commodore 128 screen, the point where X=0 and Y=0 
is at the top left corner of the screen and is referred to as the 
HOME position. In standard geometry however, the point where X 
and Y equal 0 is the bottom left corner of a graph. Figure 6-6 
shows the arrangement of the X (horizontal) and Y (vertical) 
screen coordinates and the four points at the corners of the C128 
screen. 


X Coordinate 
0,0 319,0 


Y Coordinate 


0,199 319,199 
Figure 6-6. Arrangement of X and Y Coordinates 


Here’s what the numbers mean: 


@ 1 is the color source (in this case the foreground). 
@ 160 is the starting X (horizontal) coordinate. 

@ 100 is the starting Y (vertical) coordinate. 

@ 40 is the radius. 
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Drawing a Box — The BOX Command 
Now try a box. To draw a box, type: 
80 BOX1,20,60,100,140,0,1 


This draws a solid box to the left of the circle. To find out what the 
numbers in the box statement mean, consult Chapter V, BASIC 
7.0 Encyclopaedia. The BOX statement has seven parameters 
you can select and modify to produce different types of boxes. 
Change the foreground color and draw the outline of a box to the 
right of the CIRCLE with these statements: 


90 COLOR1,9:REM CHANGE FOREGROUND COLOR 
100 BOX1,220,60,300,140,0,0 


Experiment with the BOX statement to produce different 
variations of rectangles and boxes. 


Drawing Lines Points and Other Shapes—The DRAW 
Command 


You now know how to select graphic modes and colors and how 
to display circles and boxes on the screen. Another graphics 
statement, DRAW, lets you draw lines on the screen just as you 
would with a pencil and a piece of paper. The following statement 
draws a line below the boxes and circle. 


120 DRAW 1,20,180 TO 300,180 


To erase a drawn line, change the source (1) in the DRAW 
statement to 0. The line is drawn with the background color which 
actually erases the line. Try using different coordinates and other 
sources to become accustomed to the DRAW statement. 


The DRAW statement can take another form that allows you to 
DRAW a line, change direction and then DRAW another line, so 
the lines are continuous. For example, try this statement: 


130 DRAW 1,250,0 TO 30,0 TO 40,40 TO 250,0 


This statement DRAWSs a triangle on the top of the screen. The 
four pairs of numbers represent the X and Y coordinates for the 
three points of the triangles. Notice the first and last coordinates 
are the same, since you must finish drawing the triangle on the 
same point you started. This form of draw statement gives you 
the power to DRAW almost any geometric shape, such as 
trapezoids, parallelograms and polygons. 
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The DRAW statement also has a third form. 


You can DRAW one point at a time by specifying the starting X 
and Y values as follows: 


150 DRAW 1,160,160 
This statement DRAWS a dot below the CIRCLE. 


As you Can see, the DRAW statement has versatile features 
which give you the capability to create shapes, lines, points and a 
virtually unlimited number of computer drawings on your screen. 


PAINTing Outlined Areas—The PAINT Command 


The DRAW statement allows you to outline areas on the screen. 
What if you want to fill areas within your drawn lines? That's 
where the PAINT statement comes in. The PAINT statement does 
exactly what the name implies—it fills in, or PAINTs, outlined 
areas with color. Just as a painter covers a canvas with paint, the 
PAINT statement covers the areas of the screen with one of 16 
colors. For example, type: 


160 PAINT 1,150,97 


Line 160 PAINTS the circle you have drawn in line 60. The PAINT 
statement fills a defined area until a specified boundary Is 
detected according to which source is indicated. When the 
Commodore 128 finishes PAINTing, it leaves the pixel cursor at 
the point where PAINTing began (in this case, at point 150,97). 


Here are two more PAINT statements 


180 PAINT 1,50,25 
200 PAINT 1,225,125 


Line 180 PAINTS the triangle and line 200 PAINTS the empty 
box. 


* IMPORTANT PAINTING TIP: If you choose a starting 
point in your PAINT statement which is already colored from 
the same source, Commodore 128 will not PAINT the area. 
You must choose a starting point which is entirely inside the 
boundary of the shape you want to PAINT. The starting point 
cannot be on the boundary line of a pixel that is colored from 
the same source. If you specify a PAINT coordinate that is 
the same color you are PAINTing with, nothing happens. 
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Displaying Characters on a Bit Mapped Screen—The CHAR 
Command 


So far, the example program has operated in standard bit map 
mode. Bit map mode uses a completely different area of memory 
to store the screen data than text mode (the mode in which you 
enter programs and text). If you enter bit map mode, and try to 
type characters onto the screen, nothing happens. This ts 
because the characters you are typing are being displayed on 
the text screen and you are looking at the bit map screen. 
Sometimes it is necessary to display characters on the bit map 
screen, when you are creating and plotting charts and graphs. 
The CHAR command is designed especially for this purpose. To 
display standard characters on a bit map screen, use the CHAR 
statement as follows: 


220 CHAR 1,11,24,““GRAPHICS EXAMPLE” 


This displays the text “GRAPHICS EXAMPLE” starting at line 25, 
column 12. The CHAR command can also be used in text mode, 
however it is primarily designed for the bit map screen. 


Creating a Sample Graphics Program 


So far, you have learned several graphics statements. Now tie the 
program together and see how the statements work at the same 
time. Here's how the program looks now. The color statements in 
lines 70,110, 140, 170, 190 and 210 are added to display each 
object in a different color. 
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COLOR @,1 :REM SELECT BACKGROUND COLOR 
COLOR 1,3 :REM SELECT FOREGROUND COLOR 
COLOR 4,1 :REM SELECT BORDER COLOR 
GRAPHIC 1,1 :REM SELECT BIT MAP MODE 
CIRCLE 1,166,109,49,48 :REM DRAW A CIRCLE 
COLOR 1,6 :REM CHANGE FOREGROUND COLOR 
BOX 1,20,60,190,149,0,1 :REM DRAW A BLOCK 
COLOR 1,9 :REM CHANGE FOREGROUND COLOR 
BOX 1,220,60,390,140,9,0 :REM DRAW A BOX 
COLOR 1,8 :REM CHANGE FOREGROUND COLOR 
DRAW 1,208,188 TO 360,180 :REM DRAW A LINE 
DRAW 1,250,8 TO 30,0 TO 40,48 TO 258,80:REM DRAW A TRIANGLE 
COLOR 1,15 :REM CHANGE FOREGROUND COLOR 
DRAW 1,160,169 :REM DRAW A POINT 
PAINT 1,158,97 :REM PAINT IN CIRCLE 
COLOR :REM CHANGE FOREGROUND COLOR 
PAINT :REM PAINT IN TRIANGLE 
COLOR 1,7 :REM CHANGE FOREGROUND COLOR 
PAINT 1,225,125 :REM PAINT IN EMPTY BOX 
COLOR li; tei :REM CHANGE FOREGROUND COLOR 
CHAR 1,11,24,"GRAPHICS EXAMPLE":REM DISPLAY TEXT 
FOR I=l TO 5@@@:NEXT:GRAPHIC @,1:COLOR 1,2 





Here's what the program does: 


@ Lines 10 through 30 select a COLOR for the background, 
foreground and border, respectively. 

Line 40 chooses a graphic mode. 

Line 60 displays a CIRCLE. 

Line 80 DRAWs a colored-in BOX. 

Line 100 DRAWS the outline of a box. 

Line 120 DRAWS a straight line at the bottom of the 
screen. 

Line 130 DRAWSs a triangle. 

Line 150 DRAWS a single point below the CIRCLE. 

Line 160 PAINTs the circle. 

Line 180 PAINTs the triangle. 

Line 200 PAINTs the empty box. 

Line 220 prints the CHARacters “GRAPHICS EXAMPLE” 
at the bottom of the screen. 

Line 230 delays the program so you can watch the 
graphics on the screen, switches back to text mode and 
colors the characters black. 
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If you want the graphics to remain on the screen, omit the 
GRAPHIC statement in line 230. 


Changing the size of Graphic Images—The SCALE Command 


The Commodore 128 has another graphics statement which 
offers additional power to your graphics system. The SCALE 
statement offers the ability to scale down (reduce) the size of 
graphic images on your screen. The SCALE statement also 
accomplishes another task, which can be explained as follows. 


In standard bit-map mode, the 40 column screen has 320 
horizontal coordinates and 200 vertical coordinates. In multicolor 
bit map mode, the 40 column screen has only half the horizontal 
resolution of standard bit map mode, which is 160 by 200. This 
reduction in resolution is compensated for by the additional 
Capability of using one additional color for a total of three colors, 
within an 8 by 8 character matrix. Standard bit map mode can 
only display two colors within an 8 by 8 character matrix. 


When you use the SCALE statement, both standard bit map and 
multicolor bit map modes have coordinates which are 
proportional to one another. The scale ranges from 0 through a 
maximum of 1023 horizontal coordinates. This is true regardless 
of whether you are in standard bit-map or multicolor mode. 
To SCALE your screen, use: 

SCALE 1, x, y 


and the screen coordinates range from 0 to 65535 whether you 
are in standard or multicolor high-res mode. To turn off 
SCALEIng, type: 


SCALE 0 
and the coordinates return to their normal values. 


To see the effect of SCALEing on your program add line 50: 
50 SCALE 1,500,500 
and RUN to See the effect. 


See Chapter V for more details on the SCALE command. 
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Note: SCALE comes after GRAPHIC and does not affect CHAR. 


Here are some additional example programs using the graphics 
statements you just learned. 


COLOR et 

COLOR wy.8 

COHOR 4 

GRAPHIC 1,1 

FOR I=88 TO 248 STEP 10 
CIRCLE 1,1,100,75,75 
NEXT I 

COLOR 15 

FOR I= 88 TO 250 STEP 
CIRCLE 1,1,100,50,59 
NEXT I 
GOL@ruslieg 
FOR I=58 TO 288 STEP 10 
GCLRCLE bel, 100525, 25 
NEXT I 

| FOR I=l TO 7500:NEXT I 
GRAPHIC @,1:COLOR 1,2 


GRAPHIC 1,1 

COLOR 8,1 

COLOR 4,1 

FOR I=l TO 50 

Z=INT (((RND (L))*16)+1)*1 
COLOR Ty, % 

X=INT (((RND (1))*30)+1)*19 
Y=INT (((RND (1))*2@0)+1)*10 
U=INT (((RND (1))*3@)+1)*10 
V=INT (((RND (1))*20)+1)*10 
DRAW 1,X,Y¥ TO U,V 

NEXT I 

SCNCLR 

GOTO 48 





COLOR 4, 7*COLOR™G,7<COLOR sla 
GRAPHIC 1,l 
FOR I1=480 TO 1 STEP -5 
DRAW 1,158,198 TO I,l 
NEXT I 
FOR I=l TO 400 STEP 5 
DRAW 1,158,198 TO 1,I 
NEXT I 
FOR I=48 TO 329 STEP 5 
DRAW 1,150,108 TO 1,328 
NEAT I 
FOR I=328 TO 30 STEP -5 
DRAW 1,158,100 TO 329,I 
NEXT I 
FOR I=l TO 7500:NEXT I 
GRAPHIC @,1:COLOR 1,1 


Type the examples into your computer. RUN and SAVE them for 
future reference. One of the best ways to*learn programming is to 
study program examples and see how the statements perform 
their functions. You'll soon be able to use graphics statements to 
create impressive graphics with your Commodore 128. 





If you need more information on any BASIC statement or 
command, consult Chapter V, BASIC 7.0 Encyclopaedia. 


You now have a Set of graphic commands that allows you to 
create an almost unlimited number of graphics displays. But 
Commodore 128 graphics abilities do not end here. The 
Commodore 128 has another set of statements, Known as 
SPRITE graphics, which make the creation and control of graphic 
images fast, easy and sophisticated. These high-level statements 
allow you to create sprites—moveable graphic objects—the 
C128 has its own built-in SPRite DEFinition ability. These 
statements represent the new technology for creating and 
controlling sprites. Read the next section and take your first step 
in learning computer animation. 


SPRITES: PROGRAMMABLE MOVABLE OBJECT 
BLOCKS 


You already have learned about some of the Commodore 128's 
exceptional graphics capabilities. You've learned how to use the 
first set of high-level graphics statements to draw circles, boxes, 
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lines and dots. You have also learned how to color the screen, 
switch graphic modes, paint objects on the screen and scale 
them. Now it's time to take the next step in graphics programming 
— sprite animation. 


If you have worked with the Commodore 64, you already know 
something about sprites. For those of you who are not familiar 
with the subject, a sprite is a moveable object that you can form 
into any shape or image. You can color sprites in up to one of 16 
colors. Sprites can even be multicolor. The best part is that you 
can move them on the screen. Sprites open the door to computer 
animation. 


Here is the set of sprite statements you will learn about in this 
section: 


MOVSPR 
SPRDEF 
SPRITE 
SPRSAV 
SSHAPE 


Sprite Creation 


The first step in programming sprites is designing the way the 
sprite looks. For example, suppose you want to design a rocket 
ship or a racing car sprite. Before you can color or move the 
sprite, you must first design the image. In C128 mode, you can 
create sprites in these three ways. 


1. Using the SPRITE statement within a program 
2. Using SPRite DEFinition mode (SPRDEF) 
3. Using the same method as the Commodore 64 


Using SPRITE Statements in a Program 


This method uses built-in statements so you don’t have to use 
any aids outside your program to design your sprite as the other 
two methods require. This method uses some of the graphics 
statements you learned in the previous section. Here’s the 
general procedure. The details will be added as you progress. 


1. Draw a picture with the graphics statements you learned 
in the last section, such as DRAW, CIRCLE, BOX and 
PAINT. Make the dimensions of the picture 24 pixels wide 
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by 21 pixels tall in standard bit map mode or 12 pixels 
wide by 21 tall in multicolor bit map mode. 

2. Use the SSHAPE statement to store the picture data into a 
string variable. 

3. Transfer the picture data from the string variable into a 
sprite with the SPRSAV statement. 

4. Turn on the sprite, color it, select either standard or 
multicolor mode and expand it, all with the SPRITE 
statement. 

5. Move the sprite with the MOVSPR statement. 


Drawing the Sprite Image 


Here are the actual statements that perform the sprite operations. 
When you are finished with this section, you will have written your 
first sprite program. You'll be able to RUN the program as much 
as you like, and SAVE if for future reference. 


The first step is to draw a picture (24 by 21 pixels) on the screen 
using DRAW, CIRCLE, BOX or PAINT. This example is performed 
in standard bit map mode, using a black background. Here's the 
statements that set the graphic mode and color the screen 
background black. 


5 COLOR 0,1 :REM COLOR BACKGROUND BLACK 
10 GRAPHIC 1,1 :REM SET STND BIT MAP MODE 


The following statements DRAW a picture of a racing car in the 
upper-left corner of the screen. You already learned these 
statements in the last section. 


5 COLOR @,1:COLOR 4,1:COLOR 1,2 :REM SET COLORS 
GRAPHIC 1,1 :REM SET HI-RES GRAPHIC MODE 
BOX 1,2,2,45,45 :REM PICTURE FRAME 
DRAW 1,17,18 TO 28,18 TO 26,30:REM CAR BODY 
DRAWTO 19,398 TO 17,18 :REM CAR BODY 
BOX 14a, ses aig :REM UPPER LEFT WHEEL 
BOX 1,30,10,34,18 :REM UPPER RIGHT WHEEL 
BOX 1, ldje20,.15, 28 :REM LOWER LEFT WHEEL 
BOX 1,30,20,34,28 :REM LOWER RIGHT WHEEL 
DRAW 1,26,28 TO 19,28 :REM DRAW GRILLE 
BOX 1,20,14,26,18,98,1 :REM CAR SEAT 
BOX 1,15@,35,195,40,99,1 :REM WHITE LINES 
BOX 1,158,135,195,148,99,1 :REM WHITE LINES 
BOX 1,15@,215,195,220,99,1 :REM WHITE LINES 
BOX 1,50,180,308,195 :REM FINISH OUTLINE 
CHAR 1,18,23,"FINISH" :REM DISPLAY FINISH 





RUN the program. You have just drawn a white racing car, 
enclosed in a box, in the upper-left corner of the screen. You 
have also drawn a raceway with a finish line at the bottom of the 
screen. At this point, the racing car is still only a stationary 
picture. The car isn't a sprite yet, but you have just completed the 
first step in sprite programming - creating the image. 


Storing the Sprite Data with SSHAPE 


The next step is to save the picture into a text string. Here's the 
SSHAPE statement that does it: 


45 SSHAPE A$,11,10,34,30:REM SAVE THE PICTURE IN 
A STRING 


The SSHAPE command stores the screen image (bit pattern) into 
a string variable for later processing, according to the specified 
screen coordinates. 


The numbers 11, 10, 34, 30 are the coordinates of the picture. 
You must position the coordinates in the correct place or the 
SSHAPE statement can't store your picture data correctly into the 
string variable A$. If you position the SSHAPE statement on an 
empty screen location, the data string is empty. When you later 
transfer it into a sprite, you'll realize there is no data present. 
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Make sure you position the SSHAPE statement directly on the 
correct coordinate. Also, be sure to create the picture with the 
dimensions 24 pixels wide by 21 pixels tall, the size of a single 
sprite. 


The SSHAPE statement transforms the picture of the racing car 
into a data string that the computer interprets as picture data. The 
data string, A$, stores a string of zeros and ones in the 
computer's memory that make up the picture on the screen. As in 
all computer graphics, the computer has a way it can represent 
visual graphics with bits in its memory. Each dot on the screen, 
called a pixel, has a bit in the computer's memory that controls it. 
In standard bit-map mode, if the bit in memory is equal to a 1 

(on), then the pixel on the screen is turned on. If the controlling bit 
in memory is equal to a 0 (off), then the pixel is turned off. 


Saving the Picture Data in a Sprite 


Your picture is now stored in a string. The next step is to transfer 
the picture data from the data string (A$) into the sprite data area 
so you can turn it on and animate it. The statement that does this 
is SPRSAV. Here are the statements: 


50 SPRSAV A$,1:REM STORE DATA STRING IN SPRITE 1 
55 SPRSAV A$,2:REM STORE DATA STRING IN SPRITE 2 


Your picture data is transferred into sprite 1 and sprite 2. Both 
sprites have the same data, so they look exactly the same. You 
cant see the sprites yet, because you have to turn them on. 


Turning on Sprites 


The SPRITE statement turns on a specific sprite (numbered 1 
through 8), colors it, specifies its screen priority, expands the 
Sprite’s size and determines the type of sprite display. The screen 
priority refers to whether the sprite passes in front of or behind 
the objects on the screen. Sprites can be expanded to twice their 
Original size in either the horizontal or vertical directions. The type 
of sprite display determines whether the sprite is a standard bit 
map sprite or a multicolor bit mapped sprite. Here are the two 
Statements that turn on sprites 1 and 2. 


60 SPRITE 1,1,7,0,0,0,0:REM TURN ON SPR 1 
65 SPRITE 2,1,3,0,0,0,0:REM TURN ON SPR 2 
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Here’s what each of the numbers in the SPRITE statements 
mean: 


SPRITE #,0,C,P,X,Y,M 


#— Sprite number (1 to 8) 

O— Turn On (O=1) or Off (O=0) 

C— Color (1 to 16) 

P— Priority— If P=O, sprite is in front of objects on the screen 
If P=1, sprite is behind objects on the screen 

X— If X=1, expand sprite in horizontal (X) direction 
If X=0, sprite is normal horizontal size 

Y— lf Y=1, expand sprite in vertical (Y) direction 
If Y=0, sprite is normal vertical size 

M— If M=1, sprite is multicolor 
If M=O, sprite is standard 


As you can see, the SPRITE statement is powerful, giving you 
control over many sprite qualities. 


Moving Sprites with MOVSPR 


Now that your sprite is on the screen, all you have to do is move 
it. The MOVSPR statement controls the motion of a sprite and 
allows you to animate it on the screen. The MOVSPR statement 
can be used in two ways. First, the MOVSPR statement can place 
a sprite at an absolute location on the screen, using vertical and 
horizontal coordinates. Add the following statements to your 
program: 


70 MOVSPR 1,240,70:REM POSITION SPRITE 1—X=240, 
Y=70 
80 MOVSPR 2,120,70:REM POSITION SPRITE 2—X=120, 
Y=70 
Line 70 positions sprite 1 at sprite coordinate 240,70. Line 80 
places sprite 2 at sprite coordinate 120,70. You can also use the 
MOVSPR statement to move sprites relative to their original 
positions. For example, place sprites 1 and 2 at the coordinates 
as in lines 70 and 80. You want to move them from their origina! 
locations to another location on the screen. Use the following 
statement to move sprites along a specific route on the screen: 
85 MOVSPR 1,180 # 6:REM MOVE SPRITE 1 FROM THE 
TOP TO THE BOTTOM 
87 MOVSPR 2,180 # 7:REM MOVE SPRITE 2 FROM THE 
TOP TO THE BOTTOM 
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The first number in this statement is the sprite number. The 
second number is the direction expressed as the number of 
degrees to move in the clockwise direction, relative to the original 
position of the sprite. The hash sign (#) signifies that the sprite is 
moved at the specified angle and speed relative to a starting 
position, instead of an absolute location, as in lines 70 and 80. 
The final number specifies the speed in which the sprite moves 
along its route on the screen, which ranges from 0 through 15. 


The MOVSPR command has two alternative forms. See Chapter 
V, BASIC 7.0 Encyclopaedia for these notations. 


Sprites use an entirely different coordinate plane from bit-map 
coordinates. The bit-map coordinates range from points 0,0 (the 
top left corner) to 319,199 (bottom right corner). The visible sprite 
coordinates start at point 50,24 and end at point 250,344. The 
rest of the sprite coordinates are off the screen and are not 
visible, but the sprite still moves according to them. The OFF- 
screen locations allow sprites to move smoothly onto and off the 
screen. Figure 6-7 illustrates the sprite coordinate and the visible 
sprite positions. 
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Figure 6-7. Visible Sprite Coordinates 
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Now RUN the entire program with all the steps included. You 
have just written your first sprite program. You have created a 
raceway with two racing cars. Try adding more cars and more 
objects on the screen. Experiment by drawing other sprites and 
include them tn the raceway. You are now well on the way in 
sprite programming. Use your imagination and think of other 
scenes and objects you can animate. Soon you can create all 
kinds of animated computer ‘‘movies.” 


To stop the sprites, press RUN/STOP and RESTORE at the same 
time. 


Creating a Sprite Program 


You now have a working sprite program example. Here’s the 
complete program listing: 


5 COLOR @,1:COLOR 4,1:COLOR 1,2 SET COLORS 
GRAPHIC 1,1 SET HI-RES GRAPHIC MODE 
BOX 1,2,2945,45 PICTURE FRAME 
DRAW.1,17,108 TO 28,18 TO 26,30 CAR BODY 
DRAWTO 19,38 TO 17,18 CAR BODY 
BOX 1, 11,00, i, 18 UPPER LEFT WHEEL 
BOX 1,30,10,34,18 UPPER RIGHT WHEEL 
BOX 1,11,2¢8,15,28 LOWER LEFT WHEEL 
BOX 1,30,20,34,28 LOWER RIGHT WHEEL 
DRAW 1,26,28 TO 19,28 DRAW GRILLE 
BOX 1,.20514,/26,. U8,90, 1 CAR SEAT 
BOX 1,15@,35,195,40,99,1 WHITE LINES 
BOX 1,158,135,195,1498,99,1 WHITE LINES 
BOX 1,15@,215,195,228,98,1 WHITE LINES 
BOX 1,50,1898,3090,195 FINISH OUTLINE 
CHAR 1,18,23,"FINISH" DISPLAY FINISH 
SSHAPE AS,11,10,34,3@ SAVE PICTURE INTO AS 
SPRSAV STORE AS IN SPRITE 1 
SPRSAV STORE AS IN SPRITE 2 
SPRITE TURN ON SPRITE 1 
SPRITE TURN ON SPRITE 2 
MOVSPR SPRITE 1 X=24@, Y=70 
MOVSPR SPRITE 2 X=120, Y=70 
MOVSPR MOVE SPR 1 DOWN SCREEN 
MOVSPR MOVE SPR 2 DOWN SCREEN 
FOR I=l TO 500@:NEXT I 
GRAPHIC @,1l 
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Here's what the program does: 


@ Line 5 COLORs the screen black. 

Line 10 sets standard high-resolution GRAPHIC mode. 

Line 15 DRAWS a box in the top-left corner of the screen. 

Lines 20 to 32 DRAW the racing car. 

Lines 35 to 44 DRAW the racing lanes and a finish line. 

Line 45 transfers the picture data from the racing car into 

a string variable. 

@ Lines 50 and 55 transfer the contents of the string 
variable into sprites 1 and 2. 

@ Lines 60 and 65 turn on sprites 1 and 2. 

@ Lines 70 and 80 position the sprites at the top of the 
screen. 

@ Lines 85 and 87 animate the sprites as though the two 
Cars are racing each other across the finish line. 


In this section, you have learned how to create sprites, using the 
built-in C128 graphics statements such as DRAW and BOX. You 
learned how to control the sprites, using the Commodore 128 
sprite statements. The Commodore 128 has two other ways of 
creating sprites. The first is with the built-in SPRite DEFinition 
ability, as described in the following paragraphs. The other 
method of creating sprites is similar to that used for the 
Commodore 64; see the C64 Programmer's Reference Guide for 
details on this sprite-creation technique. 


Sprite Definition Mode—The SPRDEF Command 


The Commodore 128 has a built-in SPRite DEFinition mode 
which enables you to create sprites on your Commodore 128. 
You may be familiar with the Commodore 64 method of creating 
sprites, in which you required to either have an additional sprite 
editor, or design a sprite on a piece of graph paper and then 
READ in the coded sprite DATA and POKE it into an available 
sprite block. With the new Commodore 128 sprite definition 
command SPRDEF, you can construct and edit your own sprites 
iN a Special sprite work area. 


To enter SPRDEF mode, type: 
SPRDEF 
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and press RETURN. The Commodore 128 displays a sprite grid 
on the 40 column screen. In addition, the computer displays the 
prompt: 


SPRITE NUMBER ? 


Enter a number between 1 and 8. The computer displays the 
corresponding sprite in the upper right corner of the screen. From 
now on, we will refer to the sprite grid as the work area. The work 
area has the dimensions of 24 characters wide by 21 characters 
tall. Each character position within the work area corresponds to 
1 pixel within the sprite, since a sprite is 24 pixels wide by 21 
pixels tall. While within the work area in SPRDEF mode, you have 
several editing commands available to you. Here’s a Summary of 
the commands: 


Sprite Definition Mode Command Summary 


CLR key—Erases the entire work area 

M key—Turns on/off multicolor sprite 

CTRL 1-8—Selects sprite foreground color 1-8 

« 1-8—Selects sprite foreground color 9-16 

1 key—Turns on pixels in the background color 

2 key—Turns on pixels in the foreground color 

3 key—Turns on areas in multicolor 1 

4 key—Turns on areas in multicolor 2 

A key—Turns on/off automatic cursor movement 

CRSR keys—Moves the cursor (+) within the work area 
RETURN—moves cursor to the start of the next line 

HOME key—Moves cursor to the top left corner of work 
area. 

X key—Controls horizontal expansion 

Y key—Controls vertical expansion 

Shift RETURN—Saves sprite from work area and returns to 
SPRITE NUMBER prompt 

C key—copies one sprite to another 

STOP key—Turns off displayed sprite and returns to SPRITE 
NUMBER prompt without changing the sprite 

RETURN key—(at SPRITE NUMBER prompt) Exits SPRDEF 
mode 
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Sprite Creation Procedure in SPRite DEfinition Mode 


Here's the general procedure to create a sprite in SPRite 
DEFinition mode: 


1. Clear the work area by pressing the shift and CLR/ HOME 
keys at the same time. 

2. If you want a multicolor sprite, press the M key and an 
additional cursor appears next to the original one. Two 
Cursors appear since multicolor mode actually turns on two 
pixels for every one in standard sprite mode. This is why 
multicolor mode is only half the horizontal resolution of 
standard high-res mode. 

3. Select a color for your sprite. For colors between 1 and 8, 
hold down the CONTROL key and press a key between 1 and 
8. To select color codes between 9 and 16, hold down the 
Commodore (€) key and press a key between 1 and 8. 

4. Now you are ready to start creating the shape of your sprite. 
The numbered keys 1 through 4 fill in the sprite and give it 
shape. For a single color sprite, use the 2 to fill a character 
position within the work area. Press the 1 key to erase what 
you have drawn with the 2 key. If you want to fill one 
Character position at a time, press the A key. Now you have to 
move the cursor manually with the cursor keys. If you want 
the cursor to move automatically to the right while you hold it 
down, do not press the A key since it is already set to 
automatic cursor movement. As you fill in a character position 
within the work area, you can see the corresponding pixel in 
the displayed sprite turn on. Sprite editing occurs as soon as 
you edit the work area. 


In multicolor mode, the 3 key fills two character positions 
within the work area with the multicolor 1 color, the 4 key fills 
two character positions with the multicolor 2. 


You can turn off (color the pixel in the background color) filled 
areas within the work area with the 1 key. In multicolor mode, 
the 1 key turns off two character positions at a time. 

5. While constructing your sprite, you can move freely in the 
work area without turning on or off any pixels using the 
RETURN, HOME and cursor keys. 
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6. At any time, you may expand your sprite in both the vertical 
and horizontal directions. To expand vertically, press the Y 
key. To expand horizontally, press the X key. To return to the 
normal size sprite display, press the X or Y key again. 


When a key turns on AND off of the same control, it is 
referred to as toggling, so the X and Y keys toggle the vertical 
and horizontal expansion of the sprite. 


7. When you are finshed creating your sprite and happy with the 
way it looks, save it by holding down the SHIFT key and 
pressing the RETURN key. The Commodore 128 SAVEs the 
sprite data in the appropriate sprite storage area. The 
displayed sprite in the upper right corner of the screen is 
turned off and control is returned to the SPRITE NUMBER 
prompt. If you want to create another sprite enter another 
sprite number and edit the new sprite just as you did with the 
first one. If you want to display the original sprite in the work 
area again, enter the original sprite number. If you want to exit 
SPRITE DEFinition mode, simply press RETURN at the 
SPRITE NUMBER prompt. 

8. You can copy one sprite into another with the “C” key. 

9. If you do not want to SAVE your sprite, press the STOP key. 
The Commodore 128 turns off the displayed sprite and 
returns to the SPRITE NUMBER prompt. 

10. To EXIT SPRite DEFinition mode, press the RETURN key 
while the SPRITE NUMBER prompt is displayed on the screen 
when no sprite number follows it. You can exit under either of 
the following conditions: 


Immediately after you SAVE your sprite (shift RETURN), 
immediately after you press the STOP key 


Once you have created a sprite and have exited SPRite 
DEFinition mode, your sprite data is stored in the appropriate 
sprite storage area in the Commodore 128’s memory. Since you 
are now back in the control of the BASIC language, you have to 
turn on your sprite in order to see it on the screen. To turn it on 
again, use the SPRITE command you learned previously. For 
example if you created sprite 1 in SPRDEF mode. To turn it on in 
BASIC, color it blue and expand it in both the X and Y directions 
enter this command: 


SPRITE 1,1,7,0,1,1,0 
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Now use the MOVSPR command to move it as follows: 
MOVSPR 1,45 #5 


Now you know all about SPRDEF mode. First, create the sprite, 
save the sprite data and exit from SPRDEF mode to BASIC. Next 
turn on your sprite with the SPRITE command. Move it with the 
MOVSPR command. When you're finshed programming, SAVE 
your sprite data in a binary file with the BSAVE command as 
follows: 


BSAVE “‘filename’’, BO, P3584 TO P4096 


When you want to use the sprite data again from disk, load the 
previously BSAVEd binary file with the BLOAD command as 
follows: 


BLOAD “‘filename”|, BO, P3584] 


The portion in brackets is optional. BLOAD loads data into the 
address from which it was saved if the optional portion is not 
specified. 


Now you know the new methods for creating sprites: 1) SSHAPE, 
SPRSAV, SPRITE, MOVSPR, 2) SPRDEF MODE. Experiment with 
all these methods and master sprite animation. 


See Storing Sprite Data in Binary Files later in this section for 
more information. 


Adjoining Sprites 


You have learned how to create, color, turn on and animate a 
sprite. An occasion may arise when you want to create a picture 
that is too detailed or too large to fit into a single sprite. In this 
case, you Can join two or more sprites so the picture is larger and 
more detailed than with a single sprite. By joining sprites, each 
one can move independently of one another. This gives you 
much more control over animation than a single sprite. 


This section includes an example using two adjoining sprites. 


Here's the general procedure (algorithm) for writing a program 
with two or more adjoining sprites. 
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1. Draw a picture on the screen with Commodore 128 graphics 
statements, such as DRAW, BOX and PAINT, just as you did 
in the raceway program in the last section. This time, make 
the picture twice as large as a single sprite with the 
dimensions 48 pixels wide by 21 pixels tall. 

2. Use two SSHAPE statements to store the sprites into two 
separate data strings. Position the first SSHAPE statement 
coordinates over the 24 by 21 pixel area of the first half of the 
picture you drew. Then position the second SSHAPE 
statement coordinates over the second 24 by 21 pixel area. 
Make sure you store each half of the picture data ina 
different string. For example, the first SSHAPE statement 
stores the first half of the picture into A$, and the second 
SSHAPE statement stores the second half of the picture in 
BS. 

3. Transfer the picture data from each data string into a 
separate sprite with the SPRSAV statement. 

4. Turn on each sprite with the SPRITE statement. 

5. Position the sprites so the beginning of one sprite starts at the 
pixel next to where the first sprite ends. This is the step that 
actually joins the sprites. For example, draw a picture 48 by 
21 pixels. Position the first sprite (1, for example) at location 
10,10 with this statement: 


100 MOVSPR 1,10,10 


where the first number is the sprite number, the second number 
is the horizontal (X) coordinate and the third number is the 
vertical (Y) coordinate. Position the second sprite 24 pixels to the 
right of sprite 1 with this statement: 


200 MOVSPR 2,34,10 


At this point, the two sprites are displayed directly next to each 
other. They look exactly like the picture you drew in the beginning 
of the program, using the DRAW, BOX and PAINT statements. 


6. Now you can move the sprites any way you like, again using 
the MOVSPR statement. You can move them together along 
the same path or in different directions. As you learned in the 
last section, the MOVSPR statement allows you to move 
sprites to a specific location on the screen, or to a location 
relative to the sprite’s original position. 
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The following program is an example of adjoining sprites. The 
program creates an outer space environment. It draws stars, 
a planet and a spacecraft similiar to Apollo. The spacecraft is 
drawn, then stored into two data strings, A$ and B$. The front 
of the spaceship, the capsule, is stored in sprite 1. Tne back 
half of the spaceship, the retro rocket, is stored in sprite 2. 
The spacecraft flies slowly across the screen. Since it is 
traveling so slowly and is very far from Earth, it needs to be 
launched earthward with the retro rockets. After a while, the 
retro rockets fire and propel the capsule safely toward Earth. 


Here's the program listing: 


5 COLOR 4, 
GRAPHIC 1,1 


1:COLOR @8,1:COLOR 1,2 :REM 


> REM 


FOR I=1 TO 48 


X=INT 


(RND (1) * 326) 41 


Y=INT (RND (1)*20@0)+1 


DRAW 1, 
BOX 9,9,5,79,49,,1 
BOX 1,1,5,70,48:COLOR 1,8 


X,Y:NEXT I >REM 
:REM 


:REM 


SELECT COLORS 
SET HI-RES MODE 


DRAW STARS 
CLEAR BOX 
BOX-IN SPACESHIP 


CIRCLE1,198,99,35,25:PAINT1,19%@,95:REM DRAW AND PAINT PLANET 
FOR I=98 TO 96 STEP 3:CIRCLE 1,199,1,65,1@:NEXT I 

DRAW 1,18,17T016,17T032,19T033, 20T032,39T016, 23TO10, 23T018,17 
DRAW 1,19,24T020,21T027,25T026,28:REM BOTTOM WINDOW 

DRAW 1,28,19T028,17T029,13T039,18T028,23T020,19:REM TOP WINDOW 


PAINT 1,13,2@ 


:REM 


PAINT SPACESHIP 


DRAW 1,34,187T036,20T034,30T045, 36T046, 20T045,10T034,18 

DRAW 1,45,19T051,12T057,19T057,17T051,15T046,17:REM ENGINE 1 
DRAW 1,46,22T051,24T057,22T057,29T051,27T045,29:REM ENGINE 2 
PAINT1,4@,15:PAINT1,47,12:PAINT1,47, 26:DRAW@, 45, 30TO46, 29T045, 18 
DRAW 0,34,14T044,14:DRAW G,34,21T044,21:DRAW @,34,28T044, 28 


SSHAPE 
SSHAPE 
SPRSAV 
SPRSAV 
SPRITE 
SPRITE 
MOVSPR 
MOVSPR 
MOVSPR 
MOVSPR 


AS,10,10@,33,32 
BS,34,18,57,32 


>REM 
7REM 
:REM 
7REM 
:REM 
>REM 
> REM 
:REM 
:REM 
:REM 


FOR I=1 TO 58@@:NEXT I 


MOVSPR 
MOVSPR 
MOVSPR 
MOVSPR 


1,159,150 :REM 
2,174,158 
1,270 #10 


2,98 #5 


:REM 


FOR I=l TO 1298:NEXT I 


SPRITE 
FORI=1 


2,0 
TO 5000:NEXT I 


168 GRAPHIC 6,1 
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SAVE SPRITE IN AS 

SAVE SPRITE IN BS 
SPRITE1 DATA 

SPRITE2 DATA 

ENABLE SPRITE 1 IN RED 
ENABLE SPRITE 2 IN BLUE 
POSITION SPRITE] 
POSITION SPRITE2 
ANIMATE SPRITE1L 

ANIMATE SPRITE2 


RETRO POSITION 


SPLIT SPRITES 1 & 2 


TURN OFF SPRITE 2 


RETURN TO TEXT 





Here's an explanation of the program: 


Line 5 COLORs the background black and the foreground 
white. 

Line 10 selects standard high-resolution mode and clears 
the high-res screen. 

Line 23 BOXes in a display area for the picture of the 
spacecraft in the top-left corner of the screen. 

Lines 17 through 21 DRAW the stars. 

Line 24 DRAWs and PAINTs the planet. 

Line 25 DRAWs the CIRCLEs around the planet. 

Line 26 DRAWSs the outline of the capsule portion of the 
spacecraft. 

Line 28 DRAWSs the bottom window of the space capsule. 
Line 35 DRAWSs the top window of the space capsule. 
Line 38 PAINTs the space capsule white. 

Line 40 DRAWSs the outline of the retro rocket portion of 
the spacecraft. 

Lines 42 and 43 DRAW the retro rocket engines on the 
back of the spacecraft. 

Line 44 PAINTs the retro rocket engines and DRAWs an 
outline of the back of the retro rocket in the background 
color. 

Line 45 DRAWS lines on the retro rocket portion of the 
spacecraft in the background color. (At this point, you 
have displayed only pictures on the screen. You have not 
used any sprite statements, So your rocketship is not yet a 
sprite.) 

Line 47 positions the SSHAPE coordinates above the first 
half (24 by 21 pixels), of the capsule of the spacecraft and 
stores it in a data string, A$. 

Line 48 positions the SSHAPE coordinates above the 
second half (24 by 21 pixels) of the spacecraft and stores 
it in a data string, BS. 

Line 50 transfers the data from A$ into sprite 1. 

Line 55 transfers the data from B$ into sprite 2. 

Line 60 turns on sprite 1 and colors it red. 

Line 65 turns on sprite 2 and colors it blue. 

Line 82 positions sprite 1 at coordinate 150,150. 

Line 83 positions sprite 2, 24 pixels to the right of the 
Starting coordinate of sprite 1. 

Lines 82 and 83 actually join the two sprites. 


@ Lines 85 and 87 move the joined sprites across the 
screen. 

@ Line 90 delays the program. This time delay is necessary 
for the sprites to complete the two trips across the screen. 
If you leave out the delay, the sprites do not have enough 
time to move across the screen. 

@ Lines 92 and 93 position the sprites in the center of the 
screen, and prepare the spacecraft to fire the retro 
rockets. 

@ Line 95 propels sprite 1, the space capsule, forward. The 
number 10 in line 95 specifies the speed at which the 
sprite moves. The speed ranges from 1, which is stop, to 
15, which ts lightning fast. 

@ Line 96 moves the expired retro rocket portion of the 
spacecraft backwards and off the screen. 

@ Line 97 is another time delay so the retro rocket, sprite 2, 
has time to move off the screen. 

@ Line 98 turns off sprite 2, once it is off the screen. 

@ Line 99 is another delay so the capsule can continue to 
move across the screen. 

@ Line 100 returns you to text mode. 


Working with adjoining sprites can be more interesting than 
working with a single sprite. The main points to remember are: (1) 
Make sure you position the SSHAPE coordinates at the correct 
locations on the screen, so you save the picture data properly; 
and (2) be certain to position the sprite coordinates in the correct 
location when you are joining them with the MOVSPR statement. 
In this example, you positioned sprite 2 at a location 24 pixels to 
the right of sprite 1. 


Once you master the technique of joining two sprites, try more 
than two. The more sprites you join, the better the detail and 
animation will be in your programs. 


The C128 has two additional SPRITE commands, SPRCOLOR 
and COLLISION, which are not covered in this chapter. To learn 
about these commands, refer to Chapter V, the BASIC 7.0 
Encyclopaedia. 
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Storing Sprite Data in Binary Files 


NOTE: The following explanation assumes some knowledge 
of machine language, memory locations, binary files and 
object code files. 


The Commodore 128 has two new commands, BLOAD and 
BSAVE, which make handling sprite data neat and easy. The “B” 
in BLOAD and BSAVE stand for BINARY. The BSAVE and 
BLOAD commands save and load binary files to and from disk. A 
binary file consists of either a portion of a machine language 
program, or a collection of data within a specified address range. 
You may be familair with the SAVE command within the built-in 
machine language monitor. When you use this SAVE command, 
the resulting file on disk is considered a binary file. A binary file is 
easier to work with than an object code file since you can load a 
binary file without any further preparation. An object code file 
must be loaded with a loader, as in the Commodore 64 
Assembler Development System; then the SYSTEM command 
(SYS) must be used to execute it. When loading binary files, 
remember to load them in either of these two ways: 


LOAD “binary filename’’,8,1 
or 
BLOAD “binary filename’’,BO,Pstart 
where start is 3584 if you are loading sprite data files. 


In the first method you must specify the “,1” at the end or else the 
computer treats it as a BASIC program file and loads it at the 
beginning of BASIC text. The “,1” tells the computer to load the 
binary file into the same place from which it was stored. 


You're probably wondering what this has to do with sprites. 
Here's the connection. The Commodore 128 has a dedicated 
portion of memory ranging from decimal address 3584 ($0E00) 
through 4095 ($OFFF), where sprite data is stored. This portion of 
memory takes up 512 bytes. As you know, a Sprite is 24 pixels 
wide by 21 pixels tall. Each pixel requires one bit of memory. If 
the bit in a sprite is off (equal to 0), the corresponding pixel on the 
screen is considered off and it takes on the color of the 
background. If a pixel within a sprite is on (equal to 1), the 
corresponding pixel on the screen is turned on in the foreground 
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color. The combination of zeroes and ones produces the image 
you see on the screen. 


Since a sprite is 24 by 21 pixels and each pixel requires a bit of 
storage in memory, one sprite uses up 63 bytes of Memory. See 
Figure 6-8 to understand the storage requirements for a sprite’s 
data. 


12345678 12345678 12345678 


Each Row = 24 bits = 3 bytes 
Figure 6-8. Sprite Data Requirements 


A sprite requires 63 bytes of data. Each sprite block is actually 
made up of 64 bytes; the extra byte is not used. Since the 
Commodore 128 has eight sprites and each one consists of a 64- 
byte sprite block, the computer needs 512 (8 x 64) bytes to 
represent the data of all eight sprite images. 
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The entire area where all eight sprite blocks reside starts at 
memory location 3584 ($0E00) and ends at location 4095 
(SOFFF). Figure 6-9 lists the memory address ranges where each 
individual sprite stores its data: 


SOFFF (4095 Decimal) 

]—Sprite 8 
$OFCO 

]—Sprite 7 
$OF80 

]—Sprite 6 
$0OF40 

]—Sprite 5 
$OFO0 

]—Sprite 4 
$OECO 

]—Sprite 3 
$0E80 

]—Sprite 2 
$0E40 

]—Sprite 1 
$0E00 (3584 Decimal) 


Figure 6-9. Memory Address Ranges for Sprite Storage 


BSAVE 


Once you exit from the SPRDEF mode, you can save your sprite 
data in binary sprite files. This way, you can load any collection of 
sprites back into the Commodore 128 neatly and easily. Use this 
command to save your sprite data into a binary file: 


BSAVE “binary filename’’, BO, P3584 TO P4096 


The “BO” specifies that you are saving the sprite data from bank 
0. The parameters “P3584 TO P4096” signify you are saving the 
address range 3584 ($0E00) through 4095 ($0FFF), which is the 
range where all the sprite data is stored. 


You do not have to define all of the sprites when you BSAVE 
them. The sprites you do define are BSAVEd from the correct 
sprite block. The undefined sprites are also BSAVEd in the binary 
file from the appropriate sprite block, but they do not matter to the 
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computer. It is easier to BSAVE the entire 512 bytes of all eight 
sprites, regardless if all the sprites are used, rather than BSAVE 
each sprite block individually. 


BLOAD 


Later on, when you want to use the sprites again, just BLOAD the 
entire 512 bytes for all of the sprites into the range starting at 
3584 ($0E00) and ending at 4095 (S$OFFF). Here’s the command 
to accomplish this: 


BLOAD “binary filename’’[,B0, P3584] 


Use the same filename which you BSAVEd your original sprite 
data. The BO” stands for the bank number 0 and the P3584 
specifies the starting location where the binary sprite data file is 
loaded. The last two parameters are optional. 


RRR KKEKKKKKEKEKKKKKKKEKEKEKEKKKKKRKEKKAKKK KA KKK KEKE 


In this section you have seen how much the new Commodore 7.0 
BASIC commands can simplify the usually complex process of 
creating and animating graphic images. The next section 
describes some other new BASIC 7.0 commands that do the 
same for muSic and sound. 
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SECTION 7 
Sound and Music in C128 Mode 
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INTRODUCTION 


The Commodore 128 has one of the most sophisticated built-in 
sound synthesizers available in a microcomputer. The 
synthesizer, called the Sound Interface Device (SID), is a chip 
dedicated solely to generating sound and music. The SID chip is 
capable of producing three independent voices (sounds) 
simultaneously. Each of the voices can be played in one of four 
types of sounds, called waveforms. The SID chip also has 
programmable Attack, Decay, Sustain and Release (ADSR) 
parameters. These parameters define the quality of a sound. In 
addition, the synthesizer has a filter you can use to choose 
certain sounds, eliminate others, or modify the characters of a 
sound or sounds. In this section you will learn how to control 
these parameters to produce almost any kind of sound. 


To make it easy for you to select and manipulate the many 
capabilities of the SID chip, Commodore has developed new and 
powerful BASIC music statements. 


Here are the new sound and music statements available on the 
Commodore 128: 


SOUND 
ENVELOPE 
VOL 
TEMPO 
PLAY 
FILTER 


This section explains these sound statements, one at a time, in 
the process constructing a sample musical program. When you 
are finished with this section, you will know the ingredients that 
go into a musical program. You'll be able to expand on the 
example and write programs that play intricate musical 
compositions. Eventually, you'll be able to program your own 
musical scores, make your own sound effects and play works of 
the great classical masters such as Beethoven and 
contemporary artists like the Beatles. You can even add 
computer-generated music to your graphics programs to create 
your own “‘videos.”’ 
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THE SOUND STATEMENT 


The SOUND statement is designed primarily for quick and easy 
sound effects in your programs. You will learn a more intricate 
way of playing complete musical arrangements with the other 
sound statements later in this section. 


The format for the SOUND statement is as follows: 
SOUND VC, FREQ, DUR{, DIR[, MIN[, SV[, WF[, PW))]]] 
Here's what the parameters mean: 


VC — 
FREQ — 
DUR — 


DIR — 


MIN — 


er 
WF — 


PW — 


Select VoiCe 1,2 0r3 
Set the FREQuency level of sound (0-65535) 


Set DURation of the sound (in sixtieths of a 
second) 


Set the DIRection in which the sound is 
incremented/decremented 


O = Increment the frequency upward 
1 
2 = Oscillate the frequency up and down 


select the MINimum frequency (0-65535) if the 
sweep (DIR) is specified 


Choose the Step Value for the sweep (0-32767) 
Select the WaveForm (0-3) 
0 = Triangle 


Decrement the frequency downward 


1 = Sawtooth 
2 = Variable Pulse (Square) 
3 = White Noise 


Set the Pulse Width, the width of the variable 
pulse waveform 


Note that the DIR, MIN, SV, WF and PW parameters are optional. 
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The first parameter (VC) in the SOUND statement selects which 
voice will be played. The second parameter (FREQ) determines 
the frequency of the sound, which ranges from 0 through 65535. 
The third setting (DUR) specifies the amount of time the sound is 
played. The duration is measured in 60ths of a second. If you 
want to play a sound for one second, set the duration to 60, since 
60 times 1/60 equals 1. To play the sound for two seconds, 
specify the duration to be 120. To play the sound ten seconds, 
make the duration 600, and so on. 


The fourth parameter (DIR) selects the direction in which the 
frequency of the sound is incremented or decremented. This is 
referred to as the sweep. The fifth setting (MIN) sets the minimum 
frequency where the sweep begins. The sixth setting (SV) is the 
step value of the sweep. It is similar to the step value ina 
FOR...NEXT loop. If the DIR, MIN and SV values are specified in 
the SOUND commana, the sound is played first at the original 
level specified by the FREQ parameter. Then the synthesizer 
sweeps through and plays each level of the entire range of 
frequency values starting at the MIN frequency. The sweep is 
incremented or decremented by the step value (SV) according to 
the direction specified by the DIR parameter and the frequency is 
played at the new level. 


The seventh parameter (WF) in the SOUND command selects 
the waveform for the sound. (Waveforms are explained in detail in 
the paragraph titled, Advanced Sound and Music in C128 
Mode. ) 


The final setting in the SOUND command determines the width of 
the pulse width waveform if it is selected as the waveform 
parameter. (See the Advanced Sound discussion for an 
illustration of the pulse width waveform.) 


Writing a SOUND Program 


Now it’s time to write your first SOUND program. Here's an 
example of the SOUND statement: 


10 VOL 5 
20 SOUND 1, 4096, 60 


£29 


RUN this program. The Commodore 128 plays a short beep. You 
must set the volume before you can play the sound statement, so 
line 10 sets the VOLume of the sound chip. Line 20 plays voice 1 
at a frequency of 4096 for a duration of 1 second (60 times 
1/60). Change the frequency with this statement: 


30 SOUND 1, 8192, 60 


Notice line 30 plays a higher tone than line 20. This shows the 
direct relationship between the frequency setting and the actual 
frequency of the sound. As you increase the frequency setting, 
the Commodore 128 increases the pitch of the tone. Now try this 
statement: 


40 SOUND 1, 0, 60 


This shows that a FREQ value of 0 plays the lowest frequency 
(which is so low it is inaudible). A FREQ value of 65535 plays the 
highest possible frequency. 


Now try placing the sound statement within a FOR...NEXT loop. 
This allows you to play the complete range of frequencies within 
the loop. Add these statements to your program: 


50 FOR 1 = 1 TO 65535 STEP 100 
60 SOUND 1, I, 1 
70 NEXT 


This program segment plays the variable pulse waveform in the 
range of frequencies from 1 through 65535, in increments of 100, 
from lowest frequency to highest. If you don’t specify the 
waveform, the computer selects the default value of waveform 2, 
the variable pulse waveform. 


Now change the waveform with the following program line (60) 
and try the program again: 


60 SOUND 1, I, 1, 0, 0, 0, 0, 0 


Now the program plays voice 1, using the triangle waveform, for 
the range of frequencies between 1 and 65535 in increments of 
100. This sounds like a typical sound effect in popular arcade 
games. Try waveform 1, the sawtooth waveform, and see how it 
sounds with this line: 


60 SOUND 1, I, 1, 0, 0, 0, 1, 0 
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The sawtooth waveform sounds similar to the triangle waveform 
though it has less buzz. Finally, try the white noise waveform (3). 
Substitute line 60 for this line: 


60 SOUND 1,1, 1, 0, 0, 0, 3, 0 


Now the program loop plays the white noise generator for the 
entire range of frequencies. As the frequency increases in the 
loop the pitch increases and sounds like a rocket taking off. 


Notice that so far we have not specified all of the parameters in 
the SOUND statement. Take line 60 for example: 


60 SOUND 1, I, 1, 0, 0, 0, 3, 0 


The three zeros following 1,1, 1 pertain to the sweep parameters 
within the SOUND statement. Since none of the parameters is 
specified, the SOUND does not sweep. Add this line to your 
program: 


100 SOUND 1, 49152, 240, 1, 0, 100, 1, 0 


Voice 
Frequency 
Duration 
Sweep Direction 
uency 


Minimum Sweep Freq 
Step Value for sweep 
Waveform 
Pulse Width for variable width 

waveform 








Line 100 starts the sweep frequency at 49152 and decrements 
the sweep by 100 in the downward direction, until it reaches the 
minimum sweep frequency at 0. Voice 1, using the sawtooth 
waveform (#1), plays each SOUND for four seconds (240 * 1/60 
sec.). Line 100 sounds like a bomb dropping, as in many “shoot 
‘em up” arcade games. 
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Now try changing some of the parameters in line 100. For 
instance, change the direction of the sweep to 2 (oscillate); 
change the minimum frequency of the sweep to 32768; and 
increase the step value to 3000. Your new SOUND command 
looks like this: 


110 SOUND 1, 49152, 240, 2, 32768, 3000, 1 


Line 110 makes a siren sound as though the police were right on 
your tail. For a more pleasant sound, try this: 


110 SOUND 1, 65535, 250, 0, 32768, 3000, 2, 2600 


This should remind you of a popular space-age TV show, when 
the space crew unleashed their futuristic weapons on the 
unsuspecting aliens. 


Until now, you have been programming in only one voice. You 
can produce interesting sound effects with the SOUND statement 
using up to three voices. Experiment and create a program which 
utilizes all three voices. 


Here's a Sample program that will help you understand how to 
program the Commodore 128 synthesizer chip. The program, 
when run, asks for each parameter, and then plays the sound. 
Here's the program listing. Type it into your computer and RUN it. 


SCNCLR:PRINT " SOUND PLAYER": PRINT: PRINT: PRINT 
PRINT " INPUT SOUND PARAMETERS TO PLAY":PRINT: PRINT 
INPUT "VOICE (1-3)";V 

INPUT "FREQUENCY (@-65535)";F 

INPUT "DURATION (@-32767)";D:PRINT 

INPUT "WANT TO SPECIFY OPTIONAL PARAMETERS Y/N";BS$: PRINT 
IF BS="N" THEN 130 

INPUT "SWEEP DIRECTION (@=UP,1=DOWN,2=OSCILL)";DIR 
INPU1 "MINIMUM SWEEP FREQUENCY (8-65535)";M 

INPUT "SWEEP STEP VALUE (@-32767)";S 

INPUT "WAVEFORM (@=TRI,1=SAW,2=VAR PUL,3=NOISE)";W 

IF W=2 THEN INPUT "PULSE WIDTH (0-4895)";P 

SOUND V,F,D,DIR,M,S,W,P 

INPUT "DO YOU WANT TO HEAR THE SOUND AGAIN Y/N";AS 

IF AS="yY" THEN 138 

RUN 
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Here’s a quick explanation of the program. Lines 10 and 20 
PRINT the introductory messages on the screen. Lines 30 
through 50 INPUT the voice, frequency and duration parameters. 
Line 60 asks if you want to enter the optional SOUND 
parameters, such as the sweep settings and waveform. If you 
don't want to specify these parameters, press the “N” key and 
the program jumps to line 130 and plays the sound. If you do 
want to specify the optional SOUND settings, press the “Y” key 
and the program continues with line 80. Lines 80 through 110 
specify the sweep direction, minimum sweep frequency, Sweep 
step value and waveform. Line 120 INPUTs the pulse width of the 
variable pulse waveform only if waveform 2 (variable pulse) is 
selected. Finally, line 130 plays the SOUND according to the 
parameters that you specified earlier in the program. 


Line 140 asks if you want to hear the SOUND again. If you do, 
press the “Y” key; otherwise, press the “N” key. Line 150 checks 
to see if you pressed the “Y” key. If you did, program control is 
returned to line 130 and the program plays the SOUND again. If 
you do not press the “Y” key, the program continues with line 
160, and the program reruns. To stop the Sound Player program, 
press the RUN/STOP and RESTORE keys at the same time. 


Random Sounds 


The following program generates random sounds using the RND 
function. Each SOUND parameter is calculated randomly. Type 
the program into your computer, SAVE it and RUN it. This 
program illustrates how many thousands of sounds you can 
produce by specifying various combinations of the SOUND 
parameters. Here's the listing: 


PRINT "VC FRQ DIR MIN SV WE :VOL 5 
R10 ——— —————— 
V=INT (RND (1)*3)+41 : VOICE 
F=INT (RND (1) *65535) : FREQUENCY 
D=INT (RND (1)*24@) : DURATION 
DIR=INT (RND (1)*3) : STEP DIRECTION 
M=INT (RND (1) *65535) : MINIMUM FREQUENCY 
S=INT (RND (1) *32767) : STEP VALUE 
W=INT (RND (1)*4) : WAVEFORM 
P=INT (RND (1)*4095) : PULSE WIDTH 
PRINT V;F;DIR;M;S;W;P:PRINT:PRINT : DISPLAY VALUES 
SOUND V,F,D,DIR,M,S,W,P : PLAY SOUND 
SLEEP 4 : WAIT A BIT 
SOUND V,@,%,DIR,8,G,W,P : SWITCH SOUND OFF 
GOTO 16 





Lines 10 and 20 PRINT parameter column headings and the 
underline. Lines 30 through 100 calculate each SOUND 
parameter within its specific range. For example, line 30 
calculates the voice number as follows: 


30 V = INT(RND(1)*3)+1 


The notation RND(1) specifies the seed value of the random 
number. The seed is the base number generated by the 
computer. The 1 tells the computer to generate a new seed each 
time the command is encountered. Since the Commodore 128 
has 3 voices, the notation * 3 tells the computer to generate a 
random number within the range 0 through 3. Notice however 
that there is no voice 0, so the +1 in line 30 tells the computer to 
generate a random number such that 1 <= Number < 4. The 
procedure for generating a random number in a specific range is 
to multiply the given random number times the maximum value of 
the parameter (in this case, 3). If the minimum value of the 
parameter is greater than zero, add to the random number a 
value that will specify the minimum value of the range of numbers 
you want to generate (in this case, 1). For instance, line 40 
generates a random number such that 0 <= Number < 65535. 
Since the minimum value is zero in this case, you do not need to 
add a value to the generated random number. 


Line 110 PRINTs the values of the parameters. Line 120 plays the 
SOUND specified by the random numbers generated in lines 30 
through 100. Lines 130 delays the program for 4 seconds while 
the sound is playing. Line 140 turns off the SOUND after the 4 
second delay. All sounds generated by this program play for 4 
seconds or less, since they are all turned off after 4 seconds with 
line 140. Finally, line 150 returns control to line 10, and the 
process is repeated until you press the RUN/STOP and 
RESTORE keys at the same time. 


So far you have experimented with sample programs using only 
the SOUND statement. Although you can use the SOUND 
statement to play musical scores, it is best suited for quick and 
easy sound effects like the ones in the dogfight program. The 
Commodore 128 has other statements designed specifically for 
song playing. The following paragraphs describe the advanced 
sound and music statements that enable you to play complex 
musical scores and arrangements with your Commodore 128 
synthesizer. 
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ADVANCED SOUND AND MUSIC IN C128 MODE 


A Brief Background: The Characteristics of Sound 


Every sound you hear is actually a sound wave traveling through 
the air. Like any wave, a sound (sine) wave can be represented 
graphically and mathematically (see Figure 7-1). 





Figure 7-1. Sine Wave 


The sound wave moves (oscillates) at a particular rate 
(frequency) which determines the overall pitch (the highness or 
lowness of the sound). 


The sound is also made up of harmonics, which are 
accompanying multiples of the overall frequency of the Sound or 
note. The combination of these harmonic sound waves give the 
note its qualities, called timbre. Figure 7-2 shows the relationship 
of basic sound frequencies and harmonics. 


RESULTANT WAVE 







FUNDAMENTAL (1ST HARMONIC) 


2NDHARMONIC 3RD HARMONIC 


Figure 7-2. Frequency and Harmonics 


The timbre of a musical tone, (i.e., the way a tone sounds,) is 
determined by the tone’s waveform. The Commodore 128 can 
generate four types of waveforms: triangle, sawtooth, variable 
pulse and noise. See Figure 7-3 for a graphic representation of 
these four waveforms. 
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TRIANGLE 


SAWTOOTH 


PULSE WIOTH 


VARIABLE 
PULSE 


NOISE 


Figure 7-3. Sound Waveforms Types 


Making Music on the Commodore 128 


The ENVELOPE statement 


The volume of a sound changes throughout the duration of the 
note, from when you first hear it until it is no longer audible. These 
volume qualities are referred to as Attack, Decay, Sustain and 
Release (ADSR). Attack is the rate at which a musical note 
reaches its peak volume. Decay is the rate at which a musical 
note decreases from its peak volume to its midranged (sustain) 
level. Sustain is the level at which a musical note is played at its 
midranged volume. Release is the rate at which a musical note 
decreases from its sustain level to zero volume. The ENVELOPE 
generator controls the ADSR parameters of sound. See Figure 7- 
4 for a graphical representation of ADSR. The Commodore 128 
can change each ADSR parameter to 16 different rates. This 
gives you absolute flexibility over the envelope generator and the 
resulting properties of the volume when the sound is originated. 








i) 0 ; 


Ss 


Figure 7-4. ADSR Phases 


One of the most powerful Commodore 128 sound statements— 
the one that controls the ADSR and waveform—is the ENVELOPE 
statement. The ENVELOPE statement sets the different controls 
in the synthesizer chip which makes each sound unique. The 
ENVELOPE gives you the power to manipulate the SID 
synthesizer. With ENVELOPE, you can select particular ADSR 
settings and choose a waveform for your own music and sound 
effects. The format for the ENVELOPE statement is as follows: 


ENVELOPE e[,a[,d[,s[,r[,wf[,Pw)]l]]] 


Here’s what the letters mean: 


e€ — envelope number (0-9) 
a — attack rate (0-15) 
d — decay rate (0-15) 
S — sustain level (0-15) 
r — release rate (0-15) 
wf — waveform — 0 = triangle 
1 = sawtooth 
2 = pulse (square) 
3 = noise 
4 = ring modulation 
pw — pulse width (0-4095) 


Here are the definitions of the parameters not previously defined: 


Envelope — The properties of a musical note specified by the 
waveform and the attack, decay, Sustain and release settings of 
the note. For example, the envelope for a guitar note has a 
different ADSR and waveform than a flute. 


Waveform — The type of sound wave created by the 
combination of accompanying musical harmonics of a tone. The 
accompanying harmonic sound waves are multiples of, and are 
based on the overall frequency of the tone. The qualities of the 
tone generated by each waveform are recognizably different from 
one another and are represented graphically in Figure 7-3. 


Pulse Width — The length of time between notes, generated by 
the pulse waveform. 


Now you can realize the power of the ENVELOPE statement. It 
controls most of the musical qualities of the notes being played 
by the sound synthesizer. The Commodore 128 has 10 
predefined envelopes for 10 different musical instruments. In 
using the predefined envelopes you do not have to specify the 
ADSR parameters, waveform and pulse width settings—this is 
already done for you. All you have to do is specify the envelope 
number. The rest of the parameters are chosen automatically by 
the Commodore 128. Here are the preselected envelopes for 
different types of musical instruments: 


Envelope Wave- 


Number Instrument Attack Decay Sustain Release form Width 
0 Piano 0 9 0 0 2 1536 
1 Accordion 12 0 12 0 1 

2 Calliope 0 0 25 0 0 

3 Drum 0 5 5 0 3 

4 Flute 9 4 4 0 0 

5 Guitar 0 9 2 1 1 

6 Harpsichord 0 9 0 0 2 512 
7 Organ 0 9 9 0 2 2048 
8 Trumpet 8 9 4 1 2 512 
9 Xylophone 0 9 0 0 0 


Figure 7-5, Default Parameters for ENVELOPE Statement 


Now that you have a little background on the ENVELOPE 
statement, begin another example by entering this statement into 
your Commodore 128. 


10 ENVELOPE 0, 5, 9, 2, 2, 2, 1700 


This ENVELOPE statement redefines the default piano envelope 
(0) to the following: Attack = 5, Decay = 9, Sustain = 2, Release 
= 2, waveform remains the same (2) and the pulse width of the 
variable pulse waveform is now 1700. The piano envelope will not 
take on these properties until it is selected by a PLAY statement, 
which you will learn later in this section. 


The next step in programming music is setting the volume of the 
sound chip as follows: 
20 VOL 8 


The VOL statement sets the volume of the sound chip between 0 
and 15, where 15 is the maximum and 0 is off (no volume). 


The TEMPO Statement 


The next step in Commodore 128 music programming is 
controlling the tempo, or speed of your tune. The TEMPO 
statement does this for you. Here’s the format: 


TEMPO n 


where n is a digit between 0 and 255 (and 255 is the fastest 
tempo). If you do not specify the TEMPO statement in your 
program, the Commodore 128 automatically sets the tempo to 8. 
Add this statement to your musical example program: 


30 TEMPO 10 


The PLAY Statement 


Now its time to learn how to play the notes in your song. You 
already know how the PRINT statement works. You play the 
notes in your tune the same way as PRINTing a text string to the 
screen, except you use the PLAY statement in place of PRINT. 
PRINT outputs text, PLAY outputs musical notes. 


Here's the general format for the play statement: 


PLAY“‘string of synthesizer control 
characters and musical notes” 


The total number of characters (including musical notes and 
synthesizer control characters) that can be put into a PLAY 
command is 255. However, since this exceeds the maximum 
number of characters (160) allowed for a single program line in 
BASIC 7.0, you have to concatenate (that is, add together) at 
least two strings to reach this length. You can avoid the need to 
concatenate strings by making sure your PLAY commands do 
not exceed 160 characters, i.e., one program line in length. (This 
is equivalent to four screen lines in 40-column mode, and two 
screen lines in 80-column mode.) By doing this, you will produce 
PLAY command strings that are easier to understand and use. 


To play musical notes, enclose the letter of the note you want to 
play within quotes. For example, here's how to play the musical 
scale: 


40 PLAY “CDEFGAB” 


This plays the notes C, D, E, F, G, A and B in the piano envelope, 
which is envelope 0. After each time you RUN this example 
program you are creating, hold down the RUN/STOP key and 
press the RESTORE key to reset the synthesizer chip. 


You have the option of specifying the duration of the note by 
preceding it in quotes with one of the following notations: 


W — Whole note 
H — Half note 

Q — Quarter note 
| — Eighth note 

S — Sixteenth note 


The default setting, if the duration is not specified, is for Whole 
(W) notes. 


You can PLAY a rest by including the following in the PLAY 
string: 


R — Rest 


You can instruct the computer to wait until all voices currently 
playing reach the end of a measure by including the following in 
quotes: 


M — Wait for end of measure 


The Commodore 128 also has synthesizer control characters you 
Can include in a PLAY string. This gives you absolute control over 
each note and allows you to change synthesizer controls within a 
string of notes. Follow the control character with a number in the 
allowable range for that character. The control characters and 
the range of numbers for each are shown in Figure 7-6. The “n” 
following the control character refers to the number you select 
from the specified range. 


Control Default 
Character Description Range Setting 
Vn Voice 1-3 1 
On Octave 0-6 4 
Tn Envelope 0-9 0 
Un Volume 0-15 9 
Xn Filter 0=off 0 
1=on 


Figure 7-6. Sound Synthesizer Control Characters 


Although the SID chip can process these control characters in 
any order, for the best results, place the control characters in 
your string in the order that they appear in Figure 7-6. 


You don't absolutely have to specify any of the control 
Characters, but you should to maximize the power from your 
synthesizer. The Commodore 128 automatically sets the 
synthesizer controls to the default settings in Figure 7-6. If you 
don't assign special control characters, the SID chip can PLAY 
only one envelope, one voice and one octave without any 
FILTERing. Specify the control characters to exercise the most 
control over the notes within your PLAY string. 


If you specify an ENVELOPE statement and select your own 
settings instead of using the default parameters from Figure 7-5, 
the envelope control character number in your PLAY string must 
match the envelope number in your ENVELOPE statement in 
order to assume the parameters you assigned. You don't have to 
specify the ENVELOPE statement at all if you just want to PLAY 
the default settings from Figure 7-6. In this case, simply select an 
envelope number with the (T) control character in the PLAY 
statement. 


Here's an example of the PLAY statement using the SID chip 
control characters within a string. Add this line to your program 
and notice the difference between this statement and the PLAY 
statement in line 40. 


50 PLAY’’M V2 05 T7 U5 XOC DEF GAB” 


This statement PLAYS the same notes as in line 40, but voice 2 is 
selected, the notes are played one octave higher (5) than line 40, 
the volume setting is turned down to 5 and the FILTER is 
specified as off. For now, leave the filter off. When you learn 
about FILTERing in the next section, you can come back and turn 
the filter on to see how it affects the notes being played. Notice 
line 50 selects a new instrument, the organ envelope, with the T7 
control character. Now your program PLAYS two different 
instruments in two of the independent voices. Add this statement 
to PLAY the third voice: 


60 PLAY “M V3 06 U7 T6 XO CDEFGAB” 


Here's how line 60 controls the synthesizer. The V3 selects the 
third voice, O6 places voice 3 one octave higher (6) than voice 
two, T6 selects the harpsichord envelope, U7 sets the volume to 

7 and XO leaves the filter off for all three voices. Now your 

program PLAYS all three voices, each one octave higher than the 
other, in three separate instruments, piano, organ and harpsichord. 
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So far, your PLAY statements only played whole notes. Add notes 
of different duration by placing duration control characters in your 
PLAY string as follows: 


70 PLAY “MV206T0U7X0OHCDQEFIGASB”’ 


Line 70 PLAYs voice 2 in octave 6 at volume level 7 with the 
redefined piano envelope (0) on and filter turned off. This 
statement PLAYs the notes C and D as half notes, E and F as 
quarter notes, G and A as eighth notes and B as a sixteenth note. 
Notice the difference between the piano envelope in line 40 and 
the redefined piano envelope in line 70. Line 40 actually sounds 
more like a piano than line 70. 


You can PLAY sharp, flat and dotted notes by preceding the 
notes within quotes with the following characters: 


# — Sharp 
$ — Flat 
. — Dotted 


A dotted note plays one-and-a-half times longer than a note that 
is not dotted. 


Now try adding sharp, flat and dotted notes with this statement: 
80 PLAY ‘““MV104T4U8X0.HCDQ#EFI$GA.SH#B’”’ 


Line 80 PLAYS voice 1 in octave 4 at volume level 8 with the flute 
envelope turned on and the filter turned off. It also PLAYS C and 
D as dotted half notes, E and F as sharp quarter notes, G and A 
as flat eighth notes and B as a sharp dotted sixteenth note. You 
can add rests (R) at any place within your PLAY string. 


Up until now your statement examples have left the filter off within 
the sound synthesizer and have not realized the true power 
behind it. Now that you have digested most of the sound and 
music statements and the SID control characters, move on to the 
next section to learn how to enhance your musical quality with 
the FILTER statement. 


1oNe 


The SID Filter 


Once you have selected the ENVELOPE, ADSR, VOLume and 
TEMPO, use the FILTER to perfect your synthesized sounds. In 
your program, the FILTER statement will precede the PLAY 
statement. First you should become comfortable with generating 
the sound and worry about FILTERing last. Since the SID chip 
has only one filter, it applies to all three voices. Your 
computerized tunes will play without FILTERing, but to take full 
advantage of your music synthesizer, use the FILTER statement 
to increase the sharpness and quality of the sound. 


In the first paragraph of this section, The Characteristics of 
Sound, we defined a sound as a sound wave traveling 
(oscillating) through the air at a particular rate. The rate at which 
a sound wave oscillates is called the wave’s frequency. Recall 
that a sound wave is made up of an overall frequency and 
accompanying harmonics, which are multiples of the overall 
frequency. See Figure 7-2. The accompanying harmonics give 
the sound its timbre, the qualities of the sound which are 
determined by the waveform. The filter within the SID chip gives 
you the ability to accent and eliminate the harmonics of a 
waveform and change its timbre. 


The SID chip filters sounds in three ways: low-pass, band-pass 
and high-pass filtering. These filtering methods are additive, 
meaning you can use more than one filter at a time. This ts 
discussed in the next section. Low-pass filters out frequencies 
above a certain level you specify, called the cutoff frequency. 
The cutoff frequency is the dividing line that marks the boundary 
of which frequency level will be played and which will not. In low- 
pass filtering, the SID chip plays all frequencies below the cutoff 
frequency and filters out the frequencies above it. As the name 
implies, the low frequencies are allowed to pass through the filter 
and the high ones are not. The low-pass filter produces full, solid 
sounds. See Figure 7-7. 
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Figure 7-7. Low-pass Filter 


Conversely, the high-pass filter allows all the frequencies above 
the cutoff frequency to pass through the chip. All the ones below 
it are filtered out. See Figure 7-8. The high-pass filter produces 
tinny, hollow sounds. 


AMOUNT PASSED 


CUTOFF 


FREQUENCY 


Figure 7-8. High-pass Filter 


The band-pass filter allows a range of frequencies partially above 
and below the cutoff frequency to pass through the SID chip. All 
other frequencies above and below the band surrounding the 
cutoff frequency are filtered out. See Figure 7-9. 


AMOUNT PASSED 


CUTOFF 


FREQUENCY 
Figure 7-9. Band-pass Filter 
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The FILTER Statement 


The FILTER statement specifies the cutoff frequency, the type of 
filter being used and the resonance. The resonance is the 
peaking effect of the sound wave frequency as it approaches the 
cutoff frequency. The resonance determines the sharpness and 
clearness of a sound: the higher the resonance, the sharper the 
sound. 


This ts the format of the FILTER statement: 
FILTER cf, Ip, bp, hp, res 


Here's what the parameters mean: 


cf — Cutoff frequency (0 - 2047) 

lp —  Low-pass filter 0 = off, 1 = on 

bp — _ Band-pass filter 0 = off, 1 = on 
hp — _ High-pass filter 0 = off, 1 = on 
res — Resonance (0 - 15) 


You can specify the cutoff frequency to be any value between 0 
and 2047. Turn on the low-pass filter by specifying a 1 as the 
second parameter in the FILTER statement. Turn on the band- 
pass filter by specifying a 1 as the third parameter and enable the 
high-pass filter with a 1 in the fourth parameter position. Turn off 
any of the three filters by placing a 0 in the respective position of 
the filter you want to disable. You can enable or disable one, two 
or all three of the filters at the same time. 


Now that you have some background on the FILTER statement, 
add this line to your sound program, but do not RUN the program 
yet. 


45 FILTER 1200, 1, 0, 0, 10 


Line 45 sets the cutoff frequency at 1200, turns on the low-pass 
filter, disables the high-pass and band-pass filters and assigns a 
10 as the resonance level. Now go back and turn the filter on in 
your PLAY statements by changing all the XO filter control 
characters to X1. Reset the sound chip by pressing RUN/STOP 
and RESTORE keys and RUN your sound program again. Notice 
the differences between the way the notes sound and how they 
sounded without the filter. Change line 45 to: 


45 FILTER 1200, 0, 1, 0, 10 
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The new line 45 turns off the low-pass filter and enables the 
band-pass filter. Press RUN/STOP and RESTORE and RUN your 
sound program again. Notice the difference between the low- 
pass and band-pass filters. Change line 45 again to: 


45 FILTER 1200, 0, 0, 1, 10 


Reset the sound chip and RUN your example program again. 
Notice the difference between the high-pass filter and the low- 
pass and band-pass filters. Experiment with different cutoff 
frequencies, resonance levels and filters to perfect the music and 
sound in your own programs. 


Tying Your Music Program Together 


Your first musical program is complete. Now you can program 
your favorite songs. Let's tie all the components together. Here's 
the program listing. Don't be alarmed, this is the same program 
you built in this section except the print statements are added so 
you know which program lines are being played. 


ENVELOPE 8,5,9,2,2,2,1780 

VOL 8 

TEMPO 18 

PRINT "LINE 39" 

PLAY "CDEFGAB" 

FILTER 1290,8,9,1,19 

PRINT "LINE 45 — FILTER OFF" 

PLAY “V2 05 T/7 U5 XG CDEEGAB" 

PRINT "SAME LINE 45 - FILTER ON" 
PLAY "V2 05 U5 Xl CDEFGAB" 

PRINT "LINE - FILTER OFF" 

PLAY "V3 06 T6 X®@ CDEFGAB" 

PRINT "SAME LINE 65 - FILTER ON" 
PLAY "v3 06 T6 Xl CDEFGAB" 

PRINT "LINE - FILTER OFF" 

PLAY "V2 06 U7 X@ HCD QEF IGA sB" 
PRINT "SAME LINE 85 - FILTER ON" 
PLAY "V2 06 U7 Xl HCD QEF IGA SB" 
PRINT "LINE 185 - FILTER OFE" 
PLAY "V1 04 T4 U8 XO H.CD Q#EF ISGA S.B" 
PRINT"SAME AS LINE 165 - FILTER ON" 
PLAY "Vl 04 T4 U8 Xl H.CD Q#EF ISGA S.B" 
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Line 10, the ENVELOPE statement, specifies the envelope for 
piano (0), which sets the attack to 0, decay to 9, sustain to 0 and 
release to 0. It also selects the variable pulse waveform with a 
pulse width of 1700. Line 15 sets the VOLume to 8. Line 20 
chooses the TEMPO to be 10. 


Line 35 FILTERs the notes that are played in lines 30 to 115. It 
sets the FILTER cutoff frequency to 1200. In addition, line 35 
turns off the low-pass and band-pass filters with the two zeros 
following the cutoff frequency (1200). The high-pass filter is 
turned on with the 1 following the two zeros. The resonance Is set 
to 10 by the last parameter in the FILTER statement. 


Line 30 PLAYS the notes C, D, E, F, G, A, B in that order. Line 45 
PLAYS the same notes as line 30, but it specifies the SID control 
characters U5 as volume level 5, V1 as voice 1 and 05 as octave 
5. Remember, the SID control characters allow you to change the 
synthesizer controls within a string and exercise the most control 
over the synthesizer. Line 65 specifies the control characters U7 
for volume level 7, V3 for voice 06 for octave 6 and XO to turn off 
the filter. Line 65 PLAYS the same notes as lines 30 and 45, but 
in a different volume, voice and octave. 


Line 85 has the same volume, voice and octave as line 65, and it 
specifies half notes for the notes C and D, quarter notes for the 
notes E and F, eighth notes for notes G and A and a sixteenth 
note for the B note. Line 105 sets the volume at 7, voice 1, octave 
4 and turns off the filter. It also specifies the C note as dotted half 
note, E as a sharp quarter note, G and A as flat eighth notes and 
B as a dotted sixteenth note. 


Advanced Filtering 


Each of the previous FILTERing examples used only one filter at 
a time. You can combine the SID chip’s three filters with each 
other to achieve different filtering effects. For example, you can 
enable the low-pass and high-pass filters at the same time to 
form a notch reject filter. A notch reject filter allows the 
frequencies below and above the cutoff to pass through the SID 
chip, while the frequencies close to the cutoff frequency are 
filtered. See Figure 7-10 for a graphic representation of a notch 
reject filter. 
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Figure 7-10. Notch Reject Filter 


You can also add either the low-pass or high-pass filter to the 
band-pass filter to obtain interesting effects. By mixing the band- 
pass filter with the low-pass filter, you can select the band of 
frequencies beneath the cutoff frequency and below. The rest are 
filtered out. 


By mixing the band-pass and the high-pass filters, you can select 
the band of frequencies above the cutoff frequency and higher. 
All the frequencies below the cutoff frequency are filtered out. 


Experiment with the different combinations of filters to see all the 
different types of accents you can place on your musical notes 
and sound effects. The filters are designed to perfect the sounds 
created by the other components of the SID chip. Once you have 
created the musical notes or sound effects with the SID chip, go 
back and add the FILTERing to your programs to make them as 
crisp and clean as possible. 


Now you have all the information you need to write your own 
musical programs in Commodore 128 BASIC. Experiment with 
the different waveforms, ADSR settings, TEMPOs and FILTERing. 
Look in a book of sheet music and enter the notes from a musical 
scale in sequence within a play string. Accent the notes in the 
string with the SID control characters. You can combine your 
Commodore 128 Music synthesizer with C128 mode graphics to 
make your own videos or “movies”, complete with sound tracks. 
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CODING A SONG FROM SHEET MUSIC 


This section provides a sample piece of sheet music and 
illustrates how to decode notes from a musical staff and translate 
them into a form the Commodore 128 can understand. This 
exercise is substantially faster and easier if you know how to read 
music. However, you don't have to be a musician to be able to 
play the tune on your Commodore 128. For those of you who 
cannot read music, Figure 7-11 shows how a typical musical staff 
is arranged and how the notes on the staff are related to the keys 
on a piano. 





Figure 7-11. Musical Staff 


Figure 7-12 is an excerpt from a composition titled Invention 13 
(Inventio 13 in Italian), by Johann Sebastian Bach. Although this 
composition was written a few hundred years ago, it can be 
played and enjoyed on the most modern of computer 
synthesizers, such as the SID chip, in the Commodore 128. Here 
are the opening measures of Invention 13. 
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Figure 7-12. Part of Bach’s Invention 13 


The best way to start coding a song into your Commodore 128 is 
by breaking the notes down into an intermediate code. Write 
down the upper staff notes on a piece of paper. Now write down 
the notes for the lower staff. Precede the note values with a 
duration code. For instance, precede an eighth note with an 8, 
precede a sixteenth note with a 16 and so on. Next, separate the 
notes so the notes on the upper staff for one measure are 
proportional in time with the notes for one measure on the lower 
Staff. 


If the musical composition had a third staff, you would separate it 
so the duration is proportional to the two other upper staffs. Once 
the notes for all the staffs are separated into equal durations, a 
separate dedicated voice would play each note for a particular 
staff. For example, voice 1 would play the upper staff, voice 2 will 
play the second staff and voice 3 would play the lowest staff if it 
existed. 


Let's say the upper staff begins with a string of four eighth notes. 
In addition, say the lower staff begins with a string of eight 
sixteenth notes. Since an eighth note Is proportional in time to two 
sixteenth notes, separate the notes as shown in Figure 7-13. 


V1= 8A 8B 8C 8D 
V2= 16D 16E 16F16G 16A16B 16C16D 
Figure 7-13. Synchronizing Notes for Two Voices 


Since the synchronization and timing in a musical composition is 
Critical, you must make Sure the notes in the upper staff for voice 
1, for example, are in time agreement with the notes in the lower 
Staff for voice 2. The first note in the upper staff in Figure 7-12 is 
an A eighth note. The first two notes for voice 2 are DandE 
sixteenth notes. In this case, you must enter the voice 1 eighth 
note in the PLAY string first, then follow the voice 2 sixteenth 
notes immediately after it. To continue the example, the second 
note in Figure 7-12 for voice 1 (the upper staff) is a B eighth note. 
The B eighth note is equal in time to the two sixteenth notes, F 
and G, which appear in the bottom staff for voice 2. In order to 
coordinate the timing, enter the B eighth note in the string for 
voice 1 and follow it with the two sixteenth notes F and G for 
voice 2. 


As a rule, always start with the note with the longer duration. For 
example, if a bar starts with a series of two sixteenth notes on the 
lower staff for voice 2 and the upper staff starts with an eighth 
note for voice 1, enter the eighth note in the string first since it 
must play for the duration while the two sixteenth notes are being 
fetched by the Commodore 128. You must give the computer 
time to play the longer note first, then PLAY the notes of shorter 
duration, or else the composition will not be synchronized. 


Here's the program that plays Invention 13. Enter it into your 
C128, SAVE it for future use and then RUN tt. 


REM INVENTION 13 BY J S BACH 

TEMPO 6 

AS="VLO4T7U8X8 V204T7U8X8":REM V1=ORGAN, V2=PIANO 
DO . 

PLAY AS 

READ AS 

LOOP UNTIL AS="END OF MUSIC" 

END 

REM **** FIRST MEASURE 

DATA V201IA V1LO3IE V202QA V103SA04CO3BEM 
DATA V202I1#G V1O3SBO4DO04IC V202SAEM 

DATA VLO4IE V202SA03C VLO3I#G V202SBEM 
DATA V1LO4IE V202SBO3DM 

REM **** SECOND MEASURE 

DATA V203IC V1O3SAE V202IA V103SA04CM 
DATA V202I1#G V1O3SBE V202IE V1LO3SBO4DM 
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DATA V1O4ICV 202SAE V1O3IA V202SA03CM 
DATA V104QR V202SBEBO3DM 

REM **** THIRD MEASURE 

DATA V203IC V1O4SRE V202IA V1O4SCEM 
DATA V203IC V1O3SA04C V202IA V1O2SEGM 
DATA V1O3IF V203SDO2A V1LO3IA V202SFAM 
DATA VLO4ID V202SDF V1O4IF V201SA02CM 
REM **** FOURTH MEASURE 

DATA V201IB VLO4SFD V202ID V103SBO4DM 
DATA V202IG V103SGB V202IB V1O3SDFM 
DATA VLO3IE V202SGE V103IG V202SEGM 
DATA V1O4IC V202SCE V1O4IE V201SGBM 
REM **** FIFTH MEASURE 

DATA V2O1IA V1O4SEC V202IC V1O3SA04CM 
DATA VLO3IF V202SDF V1O4ID V201SBO2DM 
DATA V201IG V1O3SDB V201IB V103SGBM 
DATA V1O3IE V202SCE V104IC V201SA02CM 
REM **** SIXTH MEASURE 

DATA V2O1LIF V104SCO3A V201ID V1O3SFAM 
DATA V1O3ID V201SGO02G V103IB V202SFGM 
DATA V20O1IA V104SCO3A V202I1#F V1O4SCEM 
DATA V20O1IB V1LO4SD03B V202I1#G V1O4SDEM 
REM **** SEVENTH MEASURE 

DATA V202IC V1O4SEC V202IA V1LO4SEGM 
DATA V202ID V1O4SFE V202ISB V1O4SDCM 
DATA V2021#G V1O03SBO4C V202IF V1O4SDEM 
DATA V202ID V1O4SFD V201IB V104S#GDM 
REM **** EIGHTH MEASURE 

DATA V202I1#G V1O4SBD V202IA V104SCAM 
DATA V202ID V1O4SFD V202IE V103SBO4DM 
DATA V202IF V1O3S#GB V202I1#D V104SCO3AM 
DATA V202IE V1O3SEA V202IE V1O3SB#GM 
REM **** NINTH MEASURE 

DATA V201HA V1LO3SAECEO2QAM 

REM **** END OF MUSIC **** 

DATA END OF MUSIC 


You can use the techniques described in this section to code 
your favorite sheet music and play it on your Commodore 128. 
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You now have been introduced to most of the powerful new 
commands of the BASIC 7.0 language that you can use in C128 
mode. In the following section you will learn to use both 40- and 
80-column screen displays with the Commodore 128. 
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INTRODUCTION 


In C128 and CP/M modes, you can choose between a 40- and 
80-column screen display. You could even use both in a single 
program. 


Each screen size has special uses. The 40-column screen is the 
same size screen the Commodore 64 uses. With the 40-column 
screen you can use the Commodore 128’s full graphics 
capabilities. You can draw circles, graphs, sprite characters, 
boxes and other shapes in high-resolution or multicolor graphic 
modes. You can also use sprites. 


If you are using 80-columns, you get twice the number of 
Characters per program line. In 80 column mode you can use the 
standard graphic characters and colors available through the 
keyboard. 


You can also write programs using two monitors to take 
advantage of both screen display formats with each monitor 
screen performing different aspects of the program. For example, 
text output could be displayed on the 80-column monitor while 
graphics output could be seen on the 40-column monitor. 


THE 40/80 KEY 


You can use the 40/80 key to set the screen width as either 40 
or 80 columns. Pressing this key will only have an effect when 
one of the following actions is taken: 


1. Power is turned ON. 

2. The RESET button is pressed. 

3. The RUN/STOP and RESTORE keys are pressed 
simultaneously. 


The 40/80 key acts like a SHIFT/LOCK key: it locks when you 
press it, and does not release until you press it again. If this key is 
up (not pressed) when one of the three conditions above occurs, 
the screen is set to 40 columns. If before power-up you press the 
key down, causing it to lock, and one of the three conditions 
listed above then occurs, the screen is set to 80 columns. Once 
the computer is running in one screen format (40 or 80 columns), 
you cannot switch to the other format using the 40/80 key. In this 
case you must press and release the ESC key and then press the 
X key. 
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USING PREPACKAGED 80-COLUMN SOFTWARE 


Most CP/M programs utilize an 80-column screen, as do many of 
the other business application packages you can use in C128 
mode. Since the width of a normal printed page is 80 columns, an 
80-column wordprocessor can display information on the screen 
exactly as that information will appear on paper. Spreadsheet 
programs often specify an 80-column format, in order to provide 
enough space for the necessary columns and categories of 
information. Many database packages and telecommunications 
programs also require or can use an 80-column screen. 


CREATING 80-COLUMN PROGRAMS 


In addition to running prepackaged software, the 80-column 
screen width can be useful in designing your own programs. 
You've probably noticed what happens when you type a line that 
is wider than 40 columns on a 40-column screen. The lines 
“wrap around’ that is, they continue onto the next screen line. 
This may cause confusion in reading the line, and can even lead 
to programming errors. An 80-column screen helps eliminate 
these problems. In general, an 80-column screen allows for a 
clearer screen and better organization. 


USING 40 AND 80 COLUMNS TOGETHER 


The main advantage of 40- column composite video output is the 
availability of bit mapped graphics, while 80 columns gives you 
Output for word processing and other business applications. If 
you have two monitors, you can write programs that are “shared”, 
using the text features 80 columns affords you and the graphics 
of 40 columns. A special command, (GRAPHIC 1,1) can be used 
within a program to transfer the execution of graphics commands 
to the 40-column display. If you have a dual monitor (one that 
can display both 40 and 80 column formats) you can place 
GRAPHIC 1,1 statements in your program so that graphics will be 
output In 40-column screen format. In order to view the graphic 
output, however, you will need to change the video switch on the 
monitor to 40 columns. If you write a program like this, it might be 
a good idea to include on-screen directions to the user to change 
the video switch. 
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For example, you might write a program which asked the user to 
input data, then create a bar graph based on the user’s input. The 
message “CHANGE TO 40 COLUMN TO VIEW GRAPH” would 
tell the user to switch modes and see the results. 


As noted previously, you can switch between the 80- and 40- 
column formats after power-up, with the ESCape/X sequence. 


The following example shows how dual screens can be used 
within a program: 


GRAPHIC 5,1:SCNCLR :REM SWITCH TO 8@ COLUMN AND CLEAR IT. 
PRINT “START IN 40 COLUMN BY SELECTING THE COMPOSITE VIDEO" 
PRINT “INPUT OF YOUR DUAL MONITOR." 
PRINT 
PRINT "PRESS THE RETURN KEY WHEN READY." 
GETKEY AS:IF AS <> CHRS$(13) THEN 69 
GRAPHIC 2,1 :REM SELECT SPLIT SCREEN MODE. 
CHAR 1,8,18,"BIT MAP/TEXT SPLIT SCREEN" 
FOR I = 78 TO 220 STEP 20:CIRCLE 1,1,50,30,30:NEXT I 
PRINT 
PRINT " SWITCH TO 88 COLUMN BY SELECTING THE 
PRINT " RGBI VIDEO INPUT OF YOUR DUAL MONITOR," 
PRINT " THEN PRESS THE RETURN KEY WHEN READY." 
GETKEY AS:IF AS <> CHRS$(13) THEN 140 
GRAPHIC 5,1- :REM SWITCH OUTPUT TO THE 8@ COLUMN. 
FOR J = 1 TO 184 
PRINT "YOU ARE NOW IN 8@ COLOUMN TEXT MODE." 
NEXT J:PRINT 
PRINT "NOW SWITCH BACK TO 48 COLUMN OUTPUT.":PRINT 
PRINT "PRESS THE RETURN KEY WHEN READY." 
GETKEY AS:IF AS <> CHRS(13) THEN 214 
GRAPHIC @,1 :REM SWITCH OUTPUT TO THE 40 COLUMN. 
PRINT 
FOR J = 1 TO 16 
PRINT ™ YOU ARE NOW IN 48 COLUMN TEXT OUTPUT." 
NEXT J 
END 





oat 


Each screen display format offers certain advantages: yet the two 
types of displays can be combined in a program to complement 
each other. Using a 40-column screen, you get the full power of 
advanced BASIC graphics. The 80-column display gives you 
more space for your own programs. |n addition, it lets you run the 
wide variety of software designed to run on an 80-column screen. 
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The sections of this chapter have introduced you to the many 
features and capabilities provided by the Commodore 128 in 
C128 mode. The following chapter tells you how to use the 
Commodore 128 in C64 mode. 
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USING BASIC 2.0 


The entire BASIC 2.0 language built into the Commodore 64 
computer has been incorporated into the BASIC 7.0 language of 
the Commodore 128. You can use the BASIC 2.0 commands in 
both C128 and C64 modes. Refer to Sections 3 and 4 in Chapter 
2 for a description of these commands. 


KEYBOARD CHARACTER SETS 


In the keyboard illustration in Section 3, the shaded keys are the 
ones that can be used in C64 Mode. The keyboard in C64 Mode 
has the same two character states as in C128 Mode: 


— Upper case/graphic character set 
— Upper/lower case character set 


When you enter C64 Mode, the keyboard is in the upper 
case/graphic character set, so that everything you type is in 
capital letters. ln C64 Mode you can only use one character set 
at a time. To switch back and forth between character sets, press 
the SHIFT key and the & key (the COMMODORE key) at the 
same time. 


USING THE TYPEWRITER-STYLE KEYS 


As in C128 Mode, you can use the typewriter-style keys in C64 
Mode to type both upper case letters (capitals) and lower case 

letters (Small letters). You can also type the numerals shown on 
the top row of the main keyboard. In addition, you can type the 

graphics symbols on the fronts of the keys. 


USING THE COMMAND KEYS 


Most COMMAND keys (i.e. the keys that send messages to the 
computer, like RETURN, SHIFT, CTRL, etc.) work the same in 
C64 Mode as they do in C128 Mode. 


The only difference is that in C64 Mode, you can only move the 
cursor by using the two CRSR keys at the bottom right corner of 
the main keyboard. In C128 Mode, you can also use the four 
arrow keys located just above the top right side of the main 
keyboard. 
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MOVING THE CURSOR IN C64 MODE 


In C64 Mode, you use two CRSR keys on the main keyboard and 
the SHIFT key to move the cursor, as described in Section 3. 


PROGRAMMING FUNCTION KEYS IN C64 MODE 


The four keys to the right side of the keyboard, just above the 
numeric keypad, are called function keys. The keys are marked 
F1, F3, FS and F7 on the tops and F2, F4, F6 and F8 on the fronts. 
These keys can be programmed — that is, they can be 
instructed to perform a specific task or function. For this reason, 
these keys are often called programmable function keys. 


You must hold down the SHIFT key to perform the functions 
associated with the markings on the front of the keys — that ts, 
F2, F4, F6 and F8. Therefore, these keys are sometimes called 
the SHIFTed programmable function keys. 


The function keys in C64 Mode do not have a printed character 
assigned to them. They do, however, have CHR$ codes 
assigned. In fact, each of them has two CHR$ codes - one for 
when you press the key by itself, and one for when you press the 
key while holding down the SHIFT key. To get the even- 
numbered function keys, hold down the SHIFT key while pressing 
the function key. For example, to get F2, hold down SHIFT and 
press F1. 


The CHR$ codes for the F1-F8 keys range from 133 to 140. 
However, the codes are not assigned to the keys in numerical 
order. The keys and their corresponding CHR$ codes are as 
follows: 
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You can use the function keys in your program in several ways. 
To do this, you need to use the GET statement. (See Section 4 for 
a description of the GET statement.) As an example, the program 
below prepares the F1 key to print a message on the screen. 


10 ? “PRESS F1 TO CONTINUE” 
20 GET A$:IF A$=””, THEN 20 

30 IF A$<>CHR$(133) THEN 20 
40 ?”YOU HAVE PRESSED F1” 


Lines 20 and 30 do most of the work in this program. Line 20 
makes the computer wait until a key is pressed before executing 
any more of the program. Note that when the command 
immediately after THEN is a GOTO, only the line number is 
necessary. Also note thata GOTO command can GOTO the 
same line it is on. Line 30 tells the computer to go back and wait 
for another key to be pressed unless the F1 key has been 
pressed. 
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Once you have edited a program, you will probably want to store 
it permanently so that you will be able to recall and use it at some 
later time. To do this you need either a Commodore disk drive or 
the Commodore Datassette. 


FORMATTING A DISK IN C64 MODE 


To store programs on a new (or blank) disk, you must first 

prepare the disk to receive data. This is called formatting the disk. 

Make sure that you turn on the disk drive before inserting any 

disk. 

To format a blank disk, in C64 Mode, you type this command: 
OPEN15,8,15:PRINT#15,‘‘NO:NAME,ID” =3EtgRN- 


In place of NAME, type a disk name of your choice; you can use 
up to 16 characters to identify the disk. In place of ID, type a two 
character code of your choice (such as W2 or 10). 


The cursor disappears during the formatting process. When the 
cursor blinks again, type the following command: 
CLOSE 15 38 ture 


NOTE: Once a disk is formatted in C64 or C128 mode, that disk 
can be used in either mode. 


THE SAVE COMMAND 

You can use the SAVE command to store your program on disk 
or tape. 

SAVEing on a Disk 


If you have a Commodore single disk drive, you Can store your 
program on disk by typing: 


SAVE “PROGRAM NAME”’,8 =REftuRN- 


The 8 indicates to the computer that you are using a disk drive to 
store your program. 
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The same rules apply for the PROGRAM NAME whether you are 
using disk or tape. The PROGRAM NAME can be anything you 
want it to be. You can use letters, numbers and/or symbols - up 
to 16 characters in all. Note that you must enclose the 
PROGRAM NAME in quotation marks. The cursor on your 
computer disappears while the program is being SAVEd, but it 
returns when the process Is completed. 

SAVEing on Cassette Tape 


If you are using a Datassette to store your program, insert a blank 
tape in the recorder, rewind the tape (if necessary) and type: 


THE LOAD AND RUN COMMANDS 


Once a program has been SAVEd, you can LOAD it back into the 
computer's memory and RUN it anytime you wish. 


LOADing and RUNning from Disk 
To load your program from a disk, type: 
LOAD’ PROGRAM NAME”’,8 ‘‘S&TURN: 
Again, the 8 indicates to the computer that you are working with a 
disk drive. 


To RUN the program, tyoe RUN and press <RETURN.> 


LOADing and RUNning from Cassette 

To LOAD your program from cassette tape, type: 
LOAD “PROGRAM NAME” -S&fuRn 

If you do not know the name of the program, you can type: 
LOAD RETURN 


and the next program on the tape will be retrieved. 
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You can use the counter on the Datassette to identify the starting 
position of the programs. Then, when you want to retrieve a 
program, simply wind the tape forward from 000 to the program's 
start location, and type: 


LOAD -RETuRN- 


In this case, you do not have to specify the PROGRAM NAME; 
your program will load automatically because it is the next 
program on the tape. 


NOTE: During the LOAD process, the program being 
LOADed is not erased from the tape; it is simply copied into 
the computer. However, LOADing a program automatically 
erases any BASIC program that may have been in the 
computer's memory. 


OTHER DISK-RELATED COMMANDS 


VERIFYING A PROGRAM 


To verify that a program has been correctly saved or loaded, 
type: 


VERIFY‘‘PROGRAM NAME”,8 =RETURN- 
If the program in the computer is identical to the one on the disk, 
the screen display will respond with the letters “OK”. 
The VERIFY command also works for tape programs. You type: 
VERIFY“PROGRAM NAME” 1 -RETURA 


Note that you do not enter the comma and the number 8, since 8 
indicates that you are working with a disk program. 


DISPLAYING YOUR DISK DIRECTORY 
To see a list of the programs on your disk, first type: 
LOAD‘$” 8 =3=73RM- 


The cursor disappears during this process. When the cursor 
reappears, type: 


LIST =3EFeRA 
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A list of the programs on your disk will then be displayed. Note 
that when you load the directory, any program that was in 
memory is erased. 


INITIALIZING A DISK DRIVE 


If the disk drive's ready light is blinking, it indicates a disk error. 
You can restore the disk drive to the condition it was in before the 
error occurred by using a procedure called INITIALIZING. To 
initialize a drive, you type: 


OPEN1,8,15,’1”:CLOSE 1 -RETURN- 


If the light is still blinking, remove the disk and turn the drive off, 
then on. 


For further information on SAVEing and LOADing your programs, 
refer to your disk drive or Datassette manual. Also consult the 
LOAD and SAVE command descriptions in the Chapter V, BASIC 
7.0 Encyclopaedia. 
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WHAT CP/M 3.0 1S 


CP/M is a product of Digital Research, Inc. The version of CP/M 
used on the Commodore 128 is CP/M Plus Version 3.0. In this 
chapter, CP/M is generally referred to as CP/M 3.0, or simply 
CP/M. This chapter summarizes CP/M on the Commodore 128. 
For detailed information on CP/M 3.0, follow the instructions on 
the coupon enclosed in the box in which the Commodore 128 is 
supplied. 


CP/M 3.0, is a popular operating system for microcomputers. As 
an operating system, CP/M 3.0 manages and supervises your 
computer’s resources, including memory and disk storage, the 
console (screen and keyboard), printer, and communication 
devices. CP/M 3.0 also manages information stored in disk files. 
CP/M 3.0 can copy files from a disk to your computer's memory, 
or to a peripheral device such as a printer. To do this, CP/M 3.0 
places various programs in memory and executes them in 
response to commands you enter at your console. Once in 
memory, a program executes a set of steps that instruct your 
computer to perform a certain task. 


You can use CP/M to create your own programs, or you Can 
choose from the wide variety of available CP/M 3.0 application 
programs. 


WHAT YOU NEED TO RUN CP/M 3.0 


The general hardware requirements for CP/M 3.0 are a compute 
containing a Z80 microprocessor, a console consisting of a 
keyboard and a display screen, and at least one floppy disk drive. 
For CP/M 3.0 on the Commodore 128 Personal Computer, the 
Z80 microprocessor is built-in; the console consists of the full 
Commodore 128 keyboard, and an 80-column monitor; and the 
disk drive is the new Commodore 1571 fast disk drive. In addition, 
there is either one or two CP/M disks packed with the computer. 
If two CP/M disks are supplied, one contains the CP/M 3.0 
system and an extensive HELP utility program, and the other 
contains a number of other utility programs. If one CP/M disk is 
supplied, the system and HELP utility are on one side of that disk 
and the utility programs are on the other. 


NOTE: Although CP/M can be used with a 40-column monitor, 
the display is 80 column but with only 40 columns displayed at 
one time. To view all 80 columns of the display, you must scroll 
the screen horizontally by pressing the CONTROL key and the 
appropriate cursor key (left or right). 


CP/M+.SYS 


This is the main CP/M Plus system file. It contains all parts of the 
system that remain permanently resident in memory: the Basic 
Input/Output System (BIOS) which loads into the top of memory, 
the Basic Disk Operating System which loads into memory 
immediately below the BIOS, and the System Parameters which 
load into the bottom page of memory. 


CCP.COM 


On booting CP/M the Console Command Processor is loaded 
into nemory immediately below the BDOS. The remaining 
memory, below CCP and above page 0, is known as the 
Transient Program Area and is where applications are loaded to. 
CCP is the program which processes any input (usually entered 
from the keyboard) in response to the system prompt (A>). It 
contains the 6 built-in commands (listed in Table 14.1 on page 
14-4), and also supports the 14 console editing commands (listed 
in Table 13.1). 


Any word entered in response to the system prompt which is not 
one of the built-in commands is treated by CCP as a transient 
command, so CCP attempts to find and execute a file named as 
that word with the .COM extension. If it does not find such a file 
on the currently logged disk, it displays the word followed by a 
question mark then brings back the system prompt. 


If more than one word is entered in response to the system 
prompt, all words after the first are treated as parameters to be 
passed to the transient command. 


A language or applications program is loaded and run by invoking 
it as if it was a Command. All CP/M programs include a .COM file. 


WHAT IS ON YOUR CP/M 3.0 DISK 


show b: 

B: RW, Space 336k 
A>dir [full 

Scanning Directory... 
Sorting Directory... 


Directory for Drive A: User 0 


Name Bytes Recs Attributes Name Bytes Recs Attributes 

CCP COM 4k 25 Dir RW CPM+ SYS 23k 182 Dir RW 

DIR COM 15K 114 Dir RW FORMAT COM 5k 35 Dir RW 

HELP COM 7k 56 Dir RW HELP HLP 83k 664 Dir RW 
KEYFIG COM 10k 75 Dir RW KEYFIG HLP 9k 72 Dir RW 

PIP COM 9k 68 Dir RW 

Total Bytes = 165k Total Records = 1291 Files Found = 9 

Total lk Blocks = 165 Used/Max Dir Entries For Drive A: 15/ 64 


A>dir b: [full 
Scanning Directory... 


Sorting Directory... 


Directory For Drive B: User 0 


Name Bytes Recs Attributes Name Bytes Recs Attributes 
DATE COM 8k 25 Dir RW DATEC ASM 2k 5 Dir RW 
DATEC RSX 2k 3 Dir RW DEVICE COM 16k 58 Dir RW 
DIR COM 30k 114 Dir RW DIRLBL RSX 4k 12 Dir RW 
DUMP COM 2k 8 Dir RW ED COM 20k 73 Dir RW 
ERASE COM 8k 29 Dir RW GENCOM COM 30k 116 Dir RW 
GET COM 14k 51 Dir RW INITDIR COM 64k 250 Dir RW 
PATCH COM 6k 19 Dir Rw PIP COM 18k 68 Dir RW 
PUT COM 14k 55 Dir RW RENAME COM 6k 23 Dir RW 
SAVE COM 4k 14 Dir RW SET COM 22k 81 Dir RW 
SETDEF COM 8k 32 Dir RW SHOW COM 18k 66 Dir RW 
SUBMIT COM 12k 42 Dir RW TYPE COM 6k 24 Dir RW 


314k Total Records = 1168 Files Found = 22 
314 Used/Max Dir Entries For Drive A: 23/ 64 


Total Bytes 
Total 1k Blocks 


-COM files 


The other .COM files all contain transient commands (listed in 
Table 14.2.). 


HELP.COM displays messages, held in HELP.HLP (whose 
extension indicates it is a data file not a program file), about the 
C128 CP/M system and its commands. If you are not familiar 
with CP/M and have no other manuals or books about it, you 
may find it useful to print out any HELP you look at. Pressing 
CONTROL and P causes any screen output also to go to the 
printer: pressing CONTROL P again turns off this facility. 


Enter HELP for the list of subjects covered, or HELP C128 CP/M 
for information specific to this implementation. (The character in 
the middle of C128 CP/M is obtained by pressing the left arrow 

key at the top left of the keyboard.) If you are printing and do not 
want pauses after each screenful, then enter HELP C128 CP/M 
[NOPAGE. 


See page 14-8 for more information on Getting Help. 


Other files 


.ASM indicates an Assembler source file. 

.RSX indicates a Resident System eXtension, which is a file 
automatically loaded by a command file as and when it is 
needed. 


GETTING STARTED WITH CP/M 3.0 


The following paragraphs tell you how to start or “boot” CP/M 
3.0, how to enter and edit the command line, and how to make 
back-up copies of your CP/M 3.0 disks. 


Loading or Booting CP/M 3.0 


Loading or “booting” CP/M 3.0 means reading a copy of the 
operating system from your CP/M 3.0 System Disk into your 
computer's memory. 


You can boot CP/M 3.0 in several ways. If your computer is off, 
you can boot CP/M by first turning on your disk drive and 
inserting the CP/M 3.0 system disk, and then turning on the 
computer. CP/M 3.0 then loads automatically. If you are already 
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in C128 BASIC mode, you can boot CP/M 3.0 by inserting the 
CP/M system disk into the drive, typing the BASIC command 
BOOT and then pressing RETURN. CP/M 3.0 then loads. In C128 
mode, you can also boot CP/M by inserting the System Disk and 
pressing the RESET button. 


If you are in C64 mode, and you want to enter CP/M mode, first 
turn off the computer. Then insert the CP/M System Disk into the 
drive and turn on the computer. 


Caution: Always make sure that the disk is fully inserted in the 
drive before you close the drive door. 


In CP/M 3.0 on the Commodore 128, the user has a 59K TPA 
(Transient Program Area), which is, in effect, user RAM. 


The Opening CP/M Screen Display 


After CP/M 3.0 is loaded into memory, a message similar to the 
following is displayed on your screen: 


CPAN 3.0 te the Commodore 128 3 JUME 8 


$0 colum display 





An important part of the opening display is the following two- 
Character message: 


A> 


This is the CP/M 3.0 system prompt. The system prompt tells 
you that CP/M is ready to read a command entered by you from 
your keyboard. The prompt also tells you that drive A is your 
default drive. This means that until you tell CP/M to do otherwise, 
it looks for program and data files on the disk in drive A. It also 
tells you that you are logged in as user O, simply by the absence 
of any user number other than 0. 


NOTE: In CP/M a single disk drive is identified as drive A. This is 
equivalent to unit number 8, drive 0 in C128 and C64 modes. 
Usually, the maximum number of drives in CP/M 3.0 is four. 
Additional drives are identified as drives B, C, etc. 


THE COMMAND LINE 


CP/M 3.0 performs tasks according to specific commands that 
you type at your keyboard. These commands appear on the 
screen in what is called a command line. A CP/M 3.0 command 
line is composed of a command keyword and an optional 
command tail. The command keyword identifies a command 
(program) to be executed. The command tail can contain extra 
information for the command, such as a filename or parameters. 
The following example shows a command line. 


A>DIR MYFILE 


In this example, DIR is the command keyword and MYFILE is the 
command tail. To send the command line to CP/M 3.0 for 
processing, press the RETURN key, as indicated in this book by 
the 3sRN- symbol. 


As you type characters at the keyboard, they appear on your 
screen. The cursor, moves to the right as you type. If you make a 
typing error, press either the INST DEL key or CTRL-H to move 
the cursor to the left and correct the error. CTRL is the 
abbreviation for the CONTROL key. To specify a control 
character, hold down the CTRL key and press the appropriate 
letter key. (A list of control characters and their uses is given in 
Section 13.) 
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You can type the keyword and command tail in any combination 
of upper-case and lower-case letters. CP/M 3.0 interprets all 
letters in the command line as being upper case. 


Generally, you must type a command line directly after the 
system prompt. However, CP/M 3.0 does allow spaces between 
the prompt and the command keyword. 


Types of Commands 


CP/M 3.0 recognizes two different types of commands: built-in 
commands and transient utility commands. Built-in commands 
execute programs that reside in memory as a part of the CP/M 
operating system. Built-in commands can be executed 
immediately. Transient utility commands are stored on disk as 
program files. They must be loaded from disk to perform their 
task. You can recognize transient utility program files when a 
directory is displayed on the screen because their filenames are 
followed by a period (full stop) and COM (.COM). Section 14 
presents lists of the CP/M built-in and transient utility commands. 


For transient utilities, CP/M 3.0 checks only the command 
keyword. Many utilities require unique command tails. If you 
include a command tail, CP/M 3.0 passes it to the utility without 
checking it. A command tail cannot contain more than 128 
characters. 


How CP/M Reads Command Lines 


Use the DIR command to demonstrate how CP/M reads 
command lines. DIR, which is an abbreviation for directory, tells 
CP/M to display a directory of disk files on your screen. Type the 
DIR keyword after the system prompt, and press RETURN: 


A>DIR =36tgRe- 


CP/M responds to this command by displaying the names of all 
the files that are stored on whatever disk is in drive A. For 
example, if the CP/M system disk is in the disk drive A, a list of 
filenames like this appears on your screen: 


A: PIP COM:ED COM:CCP COM:HELP COM:HELP HLP 
A: DIR COM:CPM SYS 


CP/M 3.0 recognizes only correctly spelled command keywords. 
If you make a typing error and press RETURN before correcting 

your mistake, CP/M 3.0 repeats or “echoes” the command line, 

followed by a question mark. For example, Suppose you mistype 

the DIR command, as in the following example: 


A>DJR =S€fuRn 
CP/M replies with: 
DJR? 


This tells you that CP/M cannot find a command keyword spelled 
DJR. To correct typing errors like this, you can use the INST/DEL 
key to delete the incorrect letters. Another way to delete 
characters is to hold down the CTRL key and press H to move 
the cursor to the left. CP/M provides a number of other control 
characters that help you edit command lines. Section 13 tells 
how to use control characters to edit command lines and other 
information you enter at your console. 


DIR accepts a filename as a command tail. You can use DIR with 
a filename to see if a specific file is on the disk. For example, to 
check that the file program MYFILE is on your disk, type: 


A>DIR MYFILE -RetgRn 


CP/M 3.0 performs this task by displaying either the name of the 
file you specified, or the message: 


No File 


Be sure you type at least one space after DIR to separate the 
command keyword from the command tail. If you do not, CP/M 
3.0 responds as follows: 


A>DIRMYFILE tea 
DIRMYFILE? 


da S0 


HOW TO COPY YOUR CP/M 3.0 DISK 


Before doing anything else you should back-up your CP/M 
system disk. This can be done using either one or two disk drives. 
If using two drives these may be 1541s, 1571s, or one of each. 
The back-up disks can be new or used. You can either format 
new disks, or reformat used disks. To make back-ups use the 
FORMAT and PIP utility programs found on your CP/M system 
disk. 


1) Format the diskette using the FORMAT program, as either 
C128 single sided (if using a 1541) or C128 double sided (if 
using a 1571). (The C64 single sided option is for formatting 
disks compatible with the CP/M 2.2 package once sold for 
the Commodore 64.) 


Enter the command FORMAT, select the required disk type 
with the Cursor Down key, press RETURN, and follow the 
onscreen instructions. Press Y (Yes) or N (No) in response 
to the ‘Do you want to format another disk’ question. 


2) Use the Peripheral Interchange Program (PIP) - on the 
second surface of the original disk - to copy files. Enter PIP 
and the usual system prompt (A>) will be replaced by the 
PIP prompt (*). 


If you have a single disk drive use drive A as the source drive 
and drive E as the destination drive. Drive E is referred to as a 
virtual drive - that is, it does not exist as an actual piece of 
hardware. Put the disk to be copied from in the drive and enter 
E:=A:*.* (you will be prompted each time the source disk and the 
destination disk have to be swopped). 


If you have two disk drives, put the source disk in drive A (which 
is device 8) and the newly formatted disk in drive B (device 9 - 
set by putting the left DIP switch on the back of the 1571 down 
while the drive is switched off) and enter B:=A:* .* to copy all the 
files. 


Your original CP/M disk is a flippy - i.e. recorded as 2 single 

sides, so it must be taken out of the drive and turned over to get 
at the second side. This is required for use in a 1541, which is a 
single sided disk drive. If you have a 1541 you should copy the 2 


11-11 


surfaces onto 2 separate disks. However, if you have a 1571 you 
will find it convenient to copy both surfaces onto a standard 
double-sided disk: after copying the first side, turn over the 
original disk and copy the second side onto the same destination 
disk by again entering the copy instruction in response to the PIP 
prompt. 


You may sometimes want to make disks that just have the 
system files on them. To do this use PIP to copy the files 
CPM+.SYS and CCP.COM to the newly formatted disk. NOTE: 
Only disks that you intend to use to boot CP/M need these 2 files 
on them - putting them on other disks wastes space. 


With a single drive, enter E:=A:CPM+.SYS to copy the first file 
and then E:=A:CCP.COM to copy the second file. 


When you have finished using PIP, press RETURN to return from 
the PIP prompt to the system prompt. 


A full description of PIP can be obtained by entering HELP PIP, 
HELP PIP OPTIONS and HELP PIP EXAMPLES. 


LANGUAGES & APPLICATIONS SOFTWARE 


CP/M is just an operating system, that is a means to an end - not 
an end in itself. On its own it does not do anything useful. If you 
want to write your own programs you will need a language, either 
assembler or high level, in which to write them. If you want to play 
games or do business work you will need applications programs. 


What to Buy 


Because CP/M has been implemented on almost every 
computer ever designed that used the Intel 8080 or the Zilog Z80 
cpu, there is a very large amount of software available for running 
on CP/M systems. The most comprehensive catalogue of 
commercial software is the ‘CP/M Software Finder’ published for 
Digital Research by Que Corporation and available through good 
software retailers (ISBN 0-88-022-021-X). Since it is not 
convenient for the CP/M Users Group to supply its library on 
Commodore format disks, a selection of public domain CP/M 
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software has been made available through the Independent 
Commodore Products Users Group (ICPUG), for which 
membership application forms can be obtained by sending an 
S.a.e. to Membership Secretary, |CPUG, 30 Brancaster Road, 
Newbury Park, Ilford, Essex, 1G2 7EP, England. 


CP/M normally uses Modified Frequency Modulation (MFM) to 
record on disks. Commodore DOS normally uses Group Code 
Recording (GCR). The Commodore 1571 disk drive can read 
both, but the older 1541 can only read GCR. Off-the-shelf CP/M 
software packages only come as MFM disks. Even within MFM 
there are many different formats: the 1571 can read disks 
formatted for: 


Epson QX10 (512 byte sectors, double sided, 10 
sectors per track) 

IBM-8 SS (CP/M-86) (512 byte sectors, single sided, 8 
sectors per track) 

IBM-8 DS (CP/M-86) (512 byte sectors, double sided, 8 
sectors per track) 

IBM-9 SS (CP/M-86) (512 byte sectors, single sided, 9 
sectors per track) 

IBM-9 DS (CP/M-86) (512 byte sectors, double sided, 9 
sectors per track) 


KayPro || (512 byte sectors, single sided, 10 
sectors per track) 

KayPro IV (512 byte sectors, double sided, 10 
sectors per track) 

Osborne DD SS (1024 byte sectors, single sided, 5 
sectors per track) 

Osborne DD DS (1024 byte sectors, double sided, 5 


sectors per track) 


Therefore when buying CP/M software you must buy it on a disk 
in one of the above formats. Also, be aware that your C128 will 
run software written to run under either CP/M 2.2 or CP/M Plus 
(which is the newer name for what was originally known as 
version 3). However, CP/M-86 is the version of CP/M designed 
for use on 16-bit processors: CP/M-86 software will not run on 
your C128’s 8-bit Z80 processor, although the 1571 drive will let 
you read CP/M-86 data files. 
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If you only have a 1541 disk drive you will have to get any 
software you buy transferred from MFM format to GCR format. 
Some software retailers may be willing to do this for you, but 
there will probably be a copying charge. Alternatively, you may 
find that your local |CPUG group provides facilities to do this at its 
meetings. 


How to Install it on Your C128 


Because there are so many different computers using the CP/M 
operating system, many CP/M programs have to be configured 
for the particular hardware on which they are to be used. The 
process of installing a program on your C128 involves setting 
parameters within the software. The program manual will 
describe how to install the program if this is required. Most 
programs provide a Isit of common terminals which they support. 
lf ADM31 appears in this list, select it. If not, you will have to do a 
custom installation. 


Listed below are the entries that should be made when running 
WINSTALL.COM (the installation program that is part of the 
Wordstar package). These also provide the information that will 
be needed for installing other programs, although not all 
packages ask the same questions. 


Terminal name Commodore 128 
Screen size 
Screen height 24 
Screen width 80 
Cursor positioning 
Function code sequence 1Bh 3Dh 
Characters to be sent between line 
number and column number none 
Characters to be sent after line 
number and column number none 
Is the column number sent before 
the line number? NO 
What character is sent to the 
terminal to signify line 1? 20h 
What character is sent to the 
terminal to signify column 1? 20h 


What types of codes are sent to 
signify line and column numbers? Single byte BINARY value 
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Terminal start-up 

Function code sequence 
Terminal exit 
Function code sequence 
Highlight-on 

Function code sequence 
Highlight-off 

Function code sequence 
Erase to End of Line 
Delete Line 
Insert Line 


Does your terminal use last character 
on screen as a scroll command? 


1Bh 59h 1Bh 1Bh 1Bh 60h 
none 

1Bh 1Bh 1Bh 52h 

1Bh 1Bh1Bh 5th 

1Bh 54h 

1Bh 52h 

1Bh 45h 


YES 


Most Commodore printers require installation as a Standard 
Printer with NO Communications Protocol and Primary list device 


as the Printer Driver. 


NOTE: The h against the numbers above indicates that they are 
hexademical numbers (using base 16 instead of the decimal 


base 10). 
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SECTION 12 
Files, Disks, and Drives in CP/M 3.0 


WHAT IS AB PIE icisrics dni caes ox bacedaearanieerseiesasteetss 12-3 
CREATING A PILE. 26 chesosacccenicdgedisatdivewensedsnadessy 12-3 
NAMING A: PILE 5 ccctunssciadsy cess ohnio esse eetatasatadencees 12-4 
PIG SS CMICQIION: wc a2csssedues shew seweternseeueaesacabentces 12-4 
DRG SOSCCIIC!’ oictcccudcas bes us seer easesudonnweshepaw ays 12-4 
PICMG. cdiciauce ndinsoneeduetatdegente ee escaenereeecnds 12-4 
PICT OO x wsa.a ae canwa ue ane anb eect ace eteeeuss daeere eed 12-4 
PemoWONd. siecnccntet scents ccaie doggeuse eet auuine eee 12-5 
Sample Fil-SpeCiiCation ..<c..sseses0 ceeds saewrnveneansa 12-5 
Ser INGIMBEN cect hs pine cceneatemenseees tua an tr eceeisees 12-5 
Using Wildcard Characters to Access More Than 
ONO FIC. sc see nv esnresaneer mses eat aedeesadaSeaekenenus 12-6 
Reserved Characters ....casessitiwaveeeea rahe wnokereeguees 12-/ 
RESEIVEO FIN DES sic cicucscucdcosvakeddasap baw cnseucevaraes 12-7 


WHAT IS A FILE? 


One of CP/M’s most important tasks is to access and maintain 
files on your disks. Files in CP/M are fundamentally the same as 
in C128 or C64 modes - that is, they are collections of 
information. However, CP/M handles files somewhat differently 
than do C128 and C64 modes. This section defines the two types 
of files used in CP/M, tells how to create, name, and access a 
file, and describes how files are stored on your CP/M disks. 


As noted above, a CP/M 3.0 file is a collection of information. 
Every file must have a unique name by which CP/M identifies the 
file. A directory is also stored on each disk. The directory 
contains a list of the filenames stored on that disk and the 
locations of each file on the disk. 


There are two kinds of CP/M files: program (command) files, and 
data files. A program file contains a series of instructions that the 
computer follows step-by-step to achieve some desired result. A 
data file is usually a collection of related information (e.g. a list of 
names and addresses, the inventory of a store, the accounting 
records of a business, the text of a document). 


CREATING A FILE 


There are several ways to create a CP/M file. One way is to use 
a text editor. The CP/M text editor ED is used to create and 
name a file. You can also create a file by copying an existing file 
to a new location; you can rename the file in the process. Under 
CP/M, you can use the PIP command to copy and rename files. 
Finally, Some programs (such as MAC, a CP/M machine 
language program) create output files as they process input files. 


The ED and PIP commands are summarized in Section 14, 
together with other commonly used CP/M commands. Details on 
these and all other CP/M 3.0 commands may be found in the 
CP/M Plus User’s Guide, which you can obtain by following the 
instructions on the coupon enclosed in the box in which the C128 
computer is supplied. 
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NAMING A FILE 


File Specification 


CP/M identifies every file by a unique file specification. A file 
specification can have four parts: a drive specifier, a filename, a 
filetype, and a password. The only mandatory part is the 
filename. 


Drive Specifier 


The drive specifier is a single letter (A-P) followed by a colon. 
Each disk drive in your system is assigned a letter. When you 
include a drive specifier as part of the file specification, you are 
telling CP/M to look for the file on the disk currently in the 
specified drive. For example, if you enter: 


B:MYFILE -8E RHE 


CP/M looks in drive B for the file MYFILE. If you omit the drive 
specifier, CP/M 3.0 looks for the file in the default drive (usually 
A). 


Filename 
A filename can be from one to eight characters long, such as: 
MYFILE 


A file specification can consist simply of a filename. When you 
make up a filename, try to let the name tell you something about 
what the file contains. For example, if you have a list of customer 
names for your business, you could name the file: 


CUSTOMER 


so that the name gives you some idea of what is in the file. 


Filetype 


To help you identify files belonging to the same category, CP/M 
allows you to add an optional one- to three- character extension, 
called a filetype, to the filename. When you add a filetype to the 
filename, separate the filetype from the filename with a period. 
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Try to use letters that tell something about the file’s category. For 
example, you could add the following filetype to the file that 
contains a list of customer names: 


CUSTOMER.NAM 


When CP/M displays file specifications, it adds blanks to short 
filenames so that you can compare filetypes quickly. The 
program files that CP/M loads into memory from a disk have the 
filetype COM. DO NOT use this filetype in your own file 
specifications. 


Password 


In the Commodore 128’s CP/M 3.0 you can include a password 
as part of the file specification. The password can be from one to 
eight characters. If you include a password, separate it from the 
filetype (or filename, if no filetype is included) with a semicolon, 
as follows: 


CUSTOMER.NAM;ACCOUNT 


A password is optional. However, if a file has been protected with 
a password, you MUST enter the password as part of the file 
specification to access the file. 


Sample File Specification 


A file specification containing all four possible elements consists 
of a drive specification, a primary filename, a filetype, and a 
password, all separated by the appropriate characters or symbols 
as in the following example: 


A:DOCUMENT.LAW;SUSAN =RE&fuRN- 


User Number 


CP/M 3.0 further identifies all files by assigning each one a user 
number which ranges from 0 to 15. CP/M 3.0 assigns the user 
number to a file when the file is created. User numbers allow you 
to separate your files into 16 file groups. 
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The user number always precedes the drive identifier except for 
user 0, which is the default user number and is not displayed in 

the prompt. Here are some examples of user numbers and their 
meanings. 


4A> User number 4, drive A 
A> User number 0, drive A 
2B> User number 2, drive B 


You can use the built-in command USER to change the current 
user number like this: 


A> USER 3 -REFURN 
3A> 


You can change both the user number and the drive by entering 
the new user number and drive specifier together at the system 
prompt: 


A>3B: -REFERN- 

3B> 
Most commands can access only those files that have the 
Current user number. However, if a file resides in user 0 and Is 
marked with a special file attribute, the file can be accessed from 
any user number. 


Using Wildcard Characters to Access More Than One File 


Certain CP/M 3.0 built-in and transient commands can select 
and process several files when special wildcard characters are 
included in the filename or filetype. A wildcard is a character that 
can be used in place of some other characters. CP/M 3.0 uses 
the asterisk (*) and the question mark (?) as wildcards. For 
instance, if you use a ? as the third character in a filename, you 
are telling CP/M to let the ? stand for any character that may be 
encountered in that position. Similarly, an * tells CP/M to fill the 
filename with ? question mark as indicated. A file specification 
containing wildcards is called an ambiguous filespec and can 
refer to more than one file, because it gives CP/M 3.0 a pattern 
to match. CP/M 3.0 searches the disk directory and selects any 
file whose filename or filetype matches the pattern. For example, 
if you type: 
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then CP/M 3.0 selects all files whose filename ended in TAX and 
whose filetype is .LIB. 


Reserved Characters 

The characters in Table 12-1 have special meaning in CP/M 3.0, 
so do not use these characters in file specifications except as 
indicated. 


Table 12-1. CP/M 3.0 Reserved Characters 


Character Meaning 
a $5- 
tab space file specification delimiters 


Carriage return 
drive delimiter in file specification 
filetype delimiter in file specification 
password delimiter tn file specification 


comment delimiter at the beginning of a 
command line 


* wildcard characters in an ambiguous 
file specification. 
<>&!] +- option list delimiters 
[] option list delimiters for global and 
local options. 
() delimiters for multiple modifiers inside square 


brackets for options that have modifiers. 


/$ option delimiters in a command line. 


Reserved Filetypes 


CP/M 3.0 has already established several file groups. Table 12-2 
lists some of their filetypes with a short description of each. 
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Filetype 


ASM 
BAS 
COM 
HEX 
HLP 
$$$ 
PRN 
REL 
SUB 
SYM 
SYS 


Table 12-2. CP/M 3.0 Reserved Filetypes 


Meaning 


Assembler source file 

BASIC source program 

Z80 or equivalent machine language program 
Output file from MAC (used by HEXCOM) 
HELP message file 

Temporary file 

Print file from MAC or RMAC 

Output file from RMAL (used by LINK) 

List of commands to be executed by SUBMIT 
Symbol file from MAC, RMAC or LINK 
system file 
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This section describes how CP/M 3.0 communicates with your 
console and printer. It tells how to start and stop console and 
printer output, and edit commands you enter at your console. 


CONTROLLING CONSOLE OUTPUT 


Sometimes CP/M 3.0 displays information on your screen too 
quickly for you to read it. To ask the system to wait while you 
read the display, hold down the CONTROL (CTRL) key and press 
S. A CTRL-S keystroke sequence causes the display to pause. 
When you are ready, press CTRL-Q to resume the display. 
Pressing the NO SCROLL key will also pause the system and 
place a pause window on the status line at the bottom of the 
screen (line 25). To resume the display, press NO SCROLL 
again. If you press any key besides CTRL-Q or NO SCROLL 
during a display pause, CP/M 3.0 sounds the console bell. 


Some CP/M 3.0 utilities (like DIR and TYPE) support automatic 
paging at the console. This means that if the program's output is 
longer than the screen can display at one time, the display 
automatically halts when the screen is filled. When this occurs, 
CP/M 3.0 prompts you to press RETURN to continue. This option 
can be turned on or off using the SETDEF command. 


CONTROLLING PRINTER OUTPUT 


You can also use a control command to echo (that is, display) 
console output to the printer. To start printer echo, press CTRL-P. 
A beep occurs to tell you that echo is on. To stop, press CTRL-P 
again. (There is no beep at this point.) While printer echo is in 
effect, any characters that appear on your screen are listed at 
your printer. 


You can use printer echo with a DIR command to make a list of 
files stored on a floppy disk. You can also use CTRL-P with 
CTRL-S and CTRL-Q to make a hard copy of part of a file. Use a 
TYPE command to start a display of the file at the console. When 
the display reaches the part you need to print, press CTRL-S to 
stop the display, CTRL-P to enable printer echo, and then CTRL- 
Q to resume the display and start printing. You can use another 
CTRL-S, CTRL-P, CTRL-Q sequence to terminate printer echo. 
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CONSOLE LINE EDITING 


As noted previously, you can correct simple typing errors by 
using the INST DEL key or CTRL-H. CP/M 3.0 also supports 
additional line editing functions that you perform with control 
Characters. You can use the control characters to edit command 
lines or input lines to most programs. 


USING CONTROL CHARACTERS FOR LINE EDITING 


Using the line editing control characters listed in Table 13-1, you 
can move the cursor left and right to insert and delete characters 
in the middle of a command line. !n this way you do not have to 
retype everything to the right of your correction. 


In the following example, the user mistypes PIP, and CP/M 3.0 
returns an error message. The user recalls the erroneous 
command line by pressing CTRL-W and corrects the error (the 
underbar character represents the cursor). 


A>POP A:=B:*.* (PIP mistypeq) 

POP? 

A>POP A:=B:*.* (CTRL-W recalls the line) 

A>POP A:=B:*.* (CTRL-B moves cursor to 
beginning of line) 

A>POP A:=B:*.* (CTRL-F moves cursor to right) 

A>PP A:=B:*.* (CTRL-G deletes error) 

A>PIP A:=B:*.* (type | corrects the command 
name) 


After the command line is corrected, the user can press RETURN 
even though the cursor is in the middle of the line. A RETURN 
keystroke, (or one of the equivalent control characters) not only 
executes the command, but also stores the command in a buffer 
so that you can press CTRL-W to recall it for editing or 
re-execution. 
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When you insert a character in the middle of a line, characters to 
the right of the cursor move to the right. If the line becomes 
longer than your screen is wide, characters disappear off the 
right side of the screen. These characters are not lost. They 
reappear if you delete characters from the line or if you press 
CTRL-E when the cursor is in the middle of the line. CTRL-E 
moves all characters to the right of the cursor to the next line on 
the screen. 


Table 13-1 gives a complete list of line editing control characters 
for the CP/M 3.0 system on the Commodore 128. 


Table 13-1. Banked CP/M 3.0 Line Editing Contro! Characters 


Character Meaning 
CTRL-A Moves the cursor one character to the left. 
CTRL-B Moves the cursor to the beginning of the 


command line without having any effect on 
the contents of the line. If the cursor is at the 
beginning, CTRL-B moves it to the end of the 
line. 


CTRL-E Forces a physical carriage return but does 
not send the command line to CP/M 3.0. 
Moves the cursor to the beginning of the next 
line without erasing the previous input. 


CTRL-F Moves the cursor one character to the right. 


CTRL-G Deletes the character above the cursor. The 
cursor does not move. Characters to the right 
of the cursor move left one position. 


CTRL-H Deletes the character to the left of the cursor 
and moves the cursor left one character 
position. Characters to the right of the cursor 
move left one position. 


CTRL-I Moves the cursor to the next tab stop. Tab 
stops are automatically set at each eighth 
column. Has the same effect as pressing the 
TAB key. 
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Table 13-1. Banked CP/M 3.0 Line Editing Control Characters 


CTRL-J 


CTRL-K 


CTRL-M 


CTRL-R 


CTRL-U 


CTRL-W 


CTRL-X 
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Sends the command line to CP/M 3.0 and 
returns the cursor to the beginning of a new 
line. Has the same effect as a RETURN ora 
CTRL-M keystroke. 


Deletes from the cursor to the end of the line. 


Sends the command line to CP/M 3.0 and 
returns the cursor to the beginning of a new 
line. Has the same effect as a RETURN ora 
CTRL-J keystroke. 


Retypes the command line. Place a # 
Character at the current cursor location, 
moves the cursor to the next line, and retypes 
any partial command you typed so far. 


Discards all the characters in the command 
line, places a # character at the current 
cursor position, and moves the cursor to the 
next line. However, you can use a CTRL-W to 
recall any characters that were to the left of 
the cursor when you pressed CTRL-U. 


Recalls and displays previously entered 
command line both at the operating system 
level and within executing programs, if the 
CTRL-W is the first character entered after 
the prompt. CTRL-J, CTRL-M, CTRL-U, and 
RETURN define the command line you can 
recall. If the command line contains 
characters, CTRL-W moves the cursor to the 
end of the command line. If you press 
RETURN, CP/M 3.0 executes the recalled 
command. 


Discards all the characters to the left of the 
cursor and moves the cursor to the beginning 
of the current line. CTRL-X saves any 
characters to the right of the cursor. 


SECTION 14 
Summary of Major CP/M 3.0 


Commands 

THE TWO TYPES OF CP/M 3.0 COMMANDS.............. 14-3 
BUILT-IN COMMANDS ...............0. 0. cee ccc eee ees 14-3 
TRANSIENT UTILITY COMMANDS ......................... 14-4 
REDIRECTING INPUT AND OUTPUT ....................... 14-6 
ASSIGNING LOGICAL DEVICES ............................ 14-7 
FINDING PROGRAMS FILES .............................85. 14-7 
EXECUTING MULTIPLE COMMANDS ...................... 14-8 
TERMINATING PROGRAMS.............................006- 14-8 
GETTING HELP................... 00 ccc ccc ccc cence 14-8 


14-1 


As noted in Section 11, a CP/M 3.0 command line consists of a 
command keyword, an optional command tail, and a RETURN 
keystroke. This section describes the two kinds of commands the 
command keyword can identify, and summarizes individual 
commands and their functions. The section also gives examples 
of the use of some of the more commonly used commands. In 
addition, the section explains the concept of logical and physical 
devices under CP/M 3.0. This section then tells how CP/M 3.0 
searches for a program file on a disk, tells how to execute 
multiple commands, and how to reset the disk system. Finally, the 
section explains how to use the HELP command to get 
information on various CP/M topics including command formats 
and usage, right at the keyboard. 


THE TWO TYPES OF CP/M 3.0 COMMANDS 


There are two types of commands on CP/M 3.0: 


® Built-in commands — which identify programs in memory 
®@ Transient utility commands — which identify program 
files on a disk 


CP/M 3.0 has six built-in commands and over 20 transient utility 
commands. You can add utilities to your system by purchasing 
various CP/M 3.0-compatible application programs. If you are an 
experienced programmer, you can also write your own utilities 
that operate with CP/M 3.0. 


BUILT-IN COMMANDS 


Built-in commands are part of CP/M 3.0 that are always available 
for your use, regardless of which disk you have in which drive. 
Built-in commands are entered in the computer's memory when 
CP/M 3.0 is loaded, and are, therefore, executed more quickly 
than the transient utilities. Table 14-1 lists the Commodore 128 
CP/M 3.0 built-in commands. 


Some built-in commands have options that require support from a 
related transient utility. The related transient utility command has 
the same name as the built-in command and has a filetype of 
COM. 
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Table 14-1. Built-in Commands 


Command Function 

DIR Displays filenames of all files in the directory 
except those marked with the SYS attribute. 

DIRSYS Displays filenames of files marked with the SYS 
(system) attribute in the directory. 

ERASE Erases a filename from the disk directory and 
releases the storage space occupied by the file. 

RENAME Renames a disk file. 

TYPE Displays contents of an ASCII (TEXT) file at your 
screen. 

USER Changes to a different user number. 


TRANSIENT UTILITY COMMANDS 


The CP/M 3.0 transient utilities are listed in Table 14-2. When 
you enter a command keyword that identifies a transient utility, 
CP/M 3.0 loads the program file from the disk and passes to that 
file any filenames, data, or parameters you entered in the 
command tail. 


DIR, RENAME AND TYPE are built-in commands which have 
optional transient extensions. 


Table 14-2. Transient Utility Commands 


DATE Sets or displays the date and time. 


DEVICE Assigns logical CP/M devices to one or more 
physical devices, changes device driver 
protocol and baud rates, or sets console 
screen size. 


DIR Displays directory with files and their 
Characteristics. 
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DUMP 


ED 
ERASE 
FORMAT 


GENCOM 


GET 


HELP 


INITDIR 


KEYFIG 


PATCH 


PIP 
PUT 


RENAME 


SAVE 


SET 


SETDEF 


SHOW 
SUBMIT 
TYPE 


Displays a file in ASCII and hexadecimal 
format. 


Creates and alters ASCII files. 
Used for wildcard erase. 


Formats a CP/M disk. Clears data from 
previously used disks. 


Creates a special COM file with attached 
RSX file. 


Temporarily gets console input from a disk 
file rather than the keyboard. 

Displays information on how to use CP/M 3.0 
commands. 


Initializes a disk directory to allow time and 
date stamping. 


Allows alteration of the definition of the 
keyboard keys 


Displays or installs patches to the CP/M 
system. 


Copies files and combines files. 


Temporarily directs printer or console output 
to a disk file. 


Changes the name of a file, or a group of files 
using wildcard characters. 


Copies the contents of memory to a file. 


Sets file options including disk labels, file 
attributes, type of time and date stamping and 
password protection. 


Sets system options including the drive 
search chain. 


Displays disk and drive statistics. 
Automatically executes multiple commands. 


Display contents of text file (or group of files, 
if wildcard characters are used) on screen 
(and printer if desired). 
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REDIRECTING INPUT AND OUTPUT 


CP/M 3.0’s PUT command allows you to direct console or printer 
output to a disk file. You can use a GET command to make 
CP/M 3.0 or a utility program take console input from a disk file. 
The following examples illustrate some of the capabilities offered 
by GET and PUT. 


You can use a PUT command to direct console output to a disk 
file as well as to the console. With PUT, you can create a disk file 
containing a directory of all files on that disk, as shown in Figure 
14-1. 


A)PUT CONSOLE OUTPUT TO FILE DIR. PRN 
PUTTING CONSOLE OUTPUT TO FILE: DIR.PRN 


A)DIR 

A: FILENAME TEX FRONT TEX FRONT BAK : ONE BAK : THREE TEX 
A: FOUR TEX ONE TEX LINEDIT TEX — EXAMP1 TXT : TWO BAK 
A: TWO TEX . THREE BAK » EXAMP2 TXT 

A)TYPE DIR.PRN 

A: FILENAME TEX FRONT TEX : FRONT BAK : ONE BAK : THREE TEX 
A: FOUR TEX ONE TEX LINEDIT TEX EXAMP1 TXT : TWO BAK 
A: TWO TEX : THREE BAK . EXAMP2 TXT 


FIGURE 14-1 PUT Command Example 


A GET command can direct CP/M 3.0 or a program to read 
console input from a disk file instead of from the keyboard. If the 
file is to be read by CP/M 3.0, it must contain standard CP/M 3.0 
command lines. If the file is to be read by a utility program, it must 
contain input appropriate for that program. A file can contain both 
CP/M 3.0 command lines and program input if it also includes a 
command to start a program. 
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ASSIGNING LOGICAL DEVICES 


The minimal Commodore 128 CP/M 3.0 hardware includes a 
console consisting of a keyboard and screen display and a 1571 
disk drive. You may want to add another device to your system, 
such as a printer or a modem. To help keep track of these 
physically different inout and output devices, table 14-3 gives the 
names of CP/M 3.0 logical devices. It also shows the physical 
devices assigned to these logical devices in the Commodore 128 
CP/M 3.0 system. 


Table 14-3. CP/M 3.0 Logical Devices 


Logical Physical Device 
Device Name Device Type Assignment 
CONIN: Console input Keyboard 
CONOUT: Console output 80-column Screen 
AUXIN: Auxiliary input Null 

AUXOUT: Auxiliary output Null 

LST: List output PTR1 or PRT2 


You can change these assignments with a DEVICE command. 
For example, you can, assign AUXIN and AUXOUT to a modem 
so that your computer can use telephone lines to communicate 
with other computer users, with information services like 
Compunet and View Data Systems. 


FINDING PROGRAM FILES 


If a command keyword identifies a utility, CP/M 3.0 looks for that 
program file on the default or specified drive. It looks under the 
current user number, and then under user 0 for the same file 
marked with the SYS attribute. At any point in the search process, 
CP/M 3.0 stops the search if it finds the program file. CP/M 3.0 
then loads the program into memory and executes it. When the 
program terminates, CP/M 3.0 displays the system prompt and 
waits for your next command. However, if CP/M 3.0 does not find 
the command file, it repeats the command line followed by a 
question mark, and waits for your next command. 


EXECUTING MULTIPLE COMMANDS 


In the examples so far, CP/M 3.0 executed only one command at 
a time. CP/M 3.0 can also execute a sequence of commands. 
You can enter a sequence of commands at the system prompt, 
or you can put a frequently needed sequence of commands in a 
disk file, using a filetype of SUB. Once you have stored the 
sequence in a disk file, you can execute the sequence whenever 
you need to with a SUBMIT command. 


TERMINATING PROGRAMS 


You can use the two keystroke command CTRL-C to terminate 
program execution or reset the disk system. To enter a CTRL-C 
command, hold down the CTRL key and press C. 


Most application programs that run under CP/M and most CP/M 
transient utilities can be terminated by a CTRL-C. However, if you 
try to terminate a program while it is sending a display to the 
screen, you may need to press a CTRL-S to halt the display 
before you enter CTRL-C. 


GETTING HELP 


CP/M 3.0 includes a transient utility command called HELP that 
displays a summary of the format and use for the most common 
CP/M commands. To access HELP, simply enter the command: 


A>HELP -REtuRN 


You can press the HELP key instead of typing the word HELP 
and pressing the RETURN key. 


The list of available topics is then displayed, like this: 
Topics available: 


COMMANDS CNTRLCHARS DATE DEVICE DIR 


DUMP ED ERASE FILESPEC GENCOM GET 
HELP HEXCOM INITDIR' =LIB LINK MAC 
PATCH PIP (COPY) PUT RENAME RMAC SAVE 
SET SETDEF SHOW SID SUBMIT TYPE 
USER XREF 
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Suppose you type: 
HELP> PIP 238tuRN 
CP/M then displays the following information: 


PIP (COPY) 
Syntax: 
DESTINATION SOURCE 


PIP d: Gn filespec [Gn] =filespec [o] ,... d: [o] 


Explanation: 


The file copy program PIP copies files, combines files, and 
transfers files between disks, printers, consoles, or other devices 
attached to your computer. The first filespec is the destination. 
The second filespec is the source. Use two or more source 
filespecs separated by commas to combine two or more files into 
one file. [o] is any combination of the available options. The [Gn] 
option in the destination filespec tells PIP to copy your file to that 
user number. 


PIP with no command tail displays an * prompt and awaits your 
series of commands, entered and processed one line at a time. 
The source or destination can be any CP/M 3.0 logical device. 


The HELP facility provides information like this on all the CP/M 
3.0 built-in and transient utility commands. If you want information 
on a specific area, you can type HELP subject after the system 
prompt, where subject is a command tail describing the subject 
you are interested in. For example: 


A> HELP PIP 
At> HELP DIRSYS 


You can refer to HELP any time you need information on a 
specific command. Or you can just browse through HELP to 
broaden your knowledge of CP/M 3.0. 
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KEYBOARD ENHANCEMENTS 


Commodore has added a number of enhancements to CP/M 3.0. 
These enhancements tailor the capabilities of the Commodore 
128 to those of CP/M 3.0. This section describes these 
enhancements. 


Any key on the keyboard can be defined to generate a code or 
function, except the following keys: 


Left SHIFT key 
Right SHIFT key 
COMMODORE key 
CONTROL key 
RESTORE key 
40-80 key 

CAPS LOCK key 


In defining a key, the keyboard recognizes the following special 

functions. To indicate these functions, hold down the CONTROL 
key and the Right SHIFT key and press the desired function key 
simultaneously. 


Key Function 


CURSOR LEFT key Defines key 

CURSOR RIGHT key Defines string (points to 
function keys) 

ALT key Toggles key filter 


Defining a Key 


A user can define the code that a key can produce. Each key has 
four possible definitions: Normal, Alpha Shift, Shift, and Control. 
The Alpha Shift is toggled on/off by pressing the & key. After 
entering this mode a small box appears on the bottom of the 
screen. The first key that is pressed is the key to be defined. The 
current HEX (hexadecimal) value assigned to this key is 
displayed and the user can then type the new HEX code for the 
key, or abort by typing a non-HEX key. The following is a 
definition of the codes that can be assigned to a key. (In ALT 
mode, codes are returned to the application; see ALT Mode 
below.) 


Code Function 
00h Null (same as not pressing a key) 
01h to 7Fh Normal ASCII codes 
80h to 9Fh String assigned 
AOh to AFh 80 column character color 
BOh to BFh 80 column background color 
COh to CFh 40 column character color 
DOh to DFh 40 column background color 
EOh to EFh 40 column border color 
FOh Toggle disk status on/off 
Fih System Pause 
F2h (undefined) 
F3h 40 column screen window right 
F4h 40 column screen window left 
F5h to FFh (undefined) 
Defining a String 


This function allows the user to assign more than one key code 
to a single key. Any key that is typed in this mode is placed in the 
string. The user can see the results of typing in a long box at the 
bottom of the screen. 


NOTE: Some keys may not display what they are. To provide the 
user with control over the process of entering data, the following 
five special key functions are available. To access these 
functions, press the CONTROL and right SHIFT keys and the 
desired function keys. 
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Key Return 
RETURN Complete string definition 
+ (on main keyboard) Insert space into string 
— (on main keyboard) Delete cursor character 
Left arrow Cursor left 
Right arrow Cursor right 


Using ALT Mode 


ALT mode is a toggle function (that is, it can be switched 


between ON and 


OFF.) The default value is OFF. This function 


allows the user to send 8-bit codes to an application. 


SCREEN ENHANCEMENTS 


The screen in CP 


/M 3.0 emulates an ADM31 terminal. The 


following screen functions emulate ADM 3A operation, which is a 


subset of ADM31 


CTRL G 
CTRL H 
CTRL J 
CTRL K 
CTRLL 
CTRL M 
CTRL Z 
ESC = RC 


Additional functio 


ESC " 
ESC t 
ESC Y 
ESC . 
ESC : 
ESC * 
ESC Q 
ESC W 
ESCE 
ESC R 


operation. 


Sound Bell 

Cursor left 

Cursor down 

Cursor up 

Cursor right 

Move cursor to start of current line (CR) 
Home and clear screen 

Cursor position where R is the row location 
(with values from space to 8) and C is the 
column location (next values from space to 0), 
referenced to the status line. 


ns in ADM31 mode include: 
Clear to end of line 


Clear to end of screen 


Home and clear screen (including the 
status line) 

Insert character 

Delete character 

Insert line 

Delete line 


1O-D 


* ESC ESC ESC color# sets a screen color from a table of 16 
color entries. (These are the same color values listed in Chapter 
Il, Section 6, Figure 6-2). The color # is set as follows: 


20h to 2Fh character color 
30h to 3Fh background color 
40h to 4Fh border color (40 column only) 


The visual effects associated with following functions are visible 
only with the 80-column screen format. 


ESC > Half intensity 

ESC < Full intensity 

ESC G4 Reverse video ON 

*ESC G3 Turn underline ON 

ESC G2 Blink ON 

*ESC G1 Select the alternate character set 
ESC GO All ESC G attributes OFF 


*NOTE: This is NOT a normal ADM31 sequence. 


; i a ee ee ee ee ee 


The sections in this chapter provide a summary of the structure 
and wide-ranging capabilities of CP/M 3.0 Detailed information 
on any facet of CP/M 3.0 is given in the Digital Research, Inc. 
book, CP/M Plus User’s Guide. To obtain a copy of this, refer to 
the coupon enclosed in the box in which the Commodore 128 is 
supplied. 
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ORGANIZATION OF ENCYCLOPAEDIA 


This chapter lists BASIC 7.0 language elements. It gives a 
complete list of the rules (syntax) of Commodore 128 BASIC 7.0, 
along with a concise description of each. 


BASIC 7.0 includes all the elements of BASIC 2.0. The new 
commands, statements, functions and operators provided in 
BASIC 7.0 are printed in blue and commands which have been 
modified in BASIC 7.0 are printed in blue and in black. 


The different types of BASIC operations are listed in individual 
sections, as follows: 


1. COMMANDS and STATEMENTS: the commands used to 
edit, store and erase programs; and the BASIC program 
statements used in the numbered lines of a program. 


2. FUNCTIONS: the string, numeric and print functions. 


3. VARIABLES AND OPERATORS: the different types of 
variables, legal variable names, arithmetic operators and 
logical operators. 


4. RESERVED WORDS AND SYMBOLS: the words and 
symbols reserved for use the BASIC 7.0 language, and 
which cannot be used for any other purpose 


COMMAND AND STATEMENT FORMAT 








Command name> AUTO 

Brief definition + —Enable/disable automatic line numbering 

Command format + AUTO [line#| 

Discussion of This command turns on the automatic line-numbering fea- 
formatanduse + ture. This eases the job of entering programs. by automati- 


cally typing the line numbers for the user. AS each program 
line is entered by pressing RETURN. the next line number is 
printed on the screen. and the cursor is positioned two 
spaces to the right of the line number. The line number 
argument refers to the desired increment between line 
numbers AUTO without an argument turns off the auto tine 
numbering. as does RUN This statement can be used only 
in direct mode (outside of a program) 


EXAMPLES: 


AUTO 10 Automatically numbers program lines in 
Example(s;> increments of 10 





AUTO 50 Automatically numbers lines in increments of 50 


AUTO 






Turns off automatic line numbering 


The boldface line that defines the format consists of the following 
elements: 


DLOAD ‘“‘program name” [D0,U8}] 


keyword argument ™ additional arguments 
(possibly optional) 


The parts of the command or statement must be typed exactly as 
shown are in capital letters. Words the user supplies, such as the 
name of a program, are not capitalized. 


When quote marks ("”’) appear (usually around a program name 
or filename), the user should include them in the appropriate 
place, according to the format example. 


KEYWORDS, also called reserved words, appear in upper-case 
letters. Keywords may be typed using the full word or the 
approved abbreviation. (A full list of abbreviations is given in 
Appendix K). The keyword or abbreviation must be entered 
correctly or an error will result. The BASIC and DOS error 
messages are defined in Appendices A and B, respectively. 
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Keywords are words that are part of the BASIC language. They 
are the central part of a command or statement, and they tell the 
computer what kind of action to take. These words cannot be 
used as variable names. A complete list of reserved words and 
symbols is given in Section 20. 


ARGUMENTS, also called parameters, appear in lower-case 
letters. Arguments complement keywords by providing specific 
information to the command or statement. For example, the 
keyword LOAD tells the computer to load a program while the 
argument tells the computer which specific program to load. A 
second argument specifies from which drive to load the program. 
Arguments include filenames, variables, line numbers, etc. 


SQUARE BRACKETS [ | show optional arguments. The user 
selects any or none of the arguments listed, depending on 
requirements. 


ANGLE BRACKETS < > indicate the user MUST choose one of 
the arguments listed. 


A VERTICAL BAR| separates items in a list of arguments when 
the choices are limited to those arguments listed. When the 
vertical bar appears in a list enclosed in SQUARE BRACKETS, 
the choices are limited to the items in the list, but the user still 
has the option not to use any arguments. 


ELLIPSIS ... a sequence of three dots means an option or 
argument can be repeated more than once. 


QUOTATION MARKS “ ” enclose character strings, filenames 
and other expressions. When arguments are enclosed in 
quotation marks, the quotation marks must be included in the 
command or statement. Quotation marks are not conventions 
used to describe formats; they are required parts of a command 
or statement. 


PARENTHESES () When arguments are enclosed in 
parentheses, they must be included in the command or 
statement. Parentheses are not conventions used to describe 
formats; they are required parts of a command or statement. 


16-5 


VARIABLE refers to any valid BASIC variable names, such as X, 
A$, T%, etc. 


EXPRESSION refers to any valid BASIC expressions, such as 
A+B+2, .5*(X+3), etc. 


COMMAS (,) COLONS (:) and SEMICOLONS (;) These MUST 
be included, they are required parts of the command or 
statement. 


GRAPHIC AND SOUND COMMAND FORMAT 
Optional parameters in Graphics and Sound commands are 
represented like this: 

{,parameter] 


When parameters are omitted the comma MUST be included, this 
is because the parameters are position dependent. You must not, 
however, include commas after the last specified parameter. 


EXAMPLE: 

ENVELOPE n [,atkj[,dec][,sus][,rel][, wf][,pw] 
To alter just the rel parameter, use: 
ENVELOPE n,,,,rel 


The first three commas mark the positions of atk, dec, sus and 
the fourth is the comma for rel. The commas for wf and pw must 
not be entered. 


In the GRAPHICS commands whenever there is a coordinate 
specified by (X,Y) it is possible to replace this with a vector (X:Y). 
In this case: 


X is the distance (scaled) 
Y is the angle in degrees (0 = up; 90 = right etc). 


For example: 


LOCATE 160,100 
DRAW TO 40;45 


will draw a line at 45 degrees of length 40. 
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DISK COMMAND FORMAT 
Optional parameters in disk commands are shown thus: 


[,parameter] 

The comma is not required if the parameter is the first after the 
command itself. If other parameters which require commas are 
omitted the commas should be ommitted too. 

EXAMPLE: 

DIRECTORY [Ddrive][<ON | ,>Udevice number][,wild card] 
would in full produce: 

DIRECTORY DO ON U8,” AB*”’ 

To specify only the wild card, no comma is required. i.e. 


DIRECTORY “AB*” 


Whenever variables are used in disk commands they MUST be 
enclosed in parentheses ( ). FOR EXAMPLE: 


DIRECTORY D(DV),(A$) 


SECTION 17 
Basic Commands and 
Statements 


APPEND 
Append new data to the end of a sequential file. 


APPEND #logical file number, “‘filename’’[,Ddrive number] 
[<ON | ,>Udevice] 


This command opens the file having the specified filename, and 
positions the pointer at the end of the file. Subsequent PRINT# 
(write) statements will cause data to be appended to the end of 
this file. Default values for drive number and device number are 0 
and 8 respectively. 


Variables or Expressions used as filenames must be enclosed 
within parentheses. 


EXAMPLES: 


APPEND # 8, “MYFILE”’ 


OPEN logical file 8 called “MYFILE” for appending with 
subsequent PRINT # statements. 


APPEND # 7, (A$),D0,U9 


OPEN logical file named by the variable in A$ on drive 0, device 
number 9 and prepare to APPEND. 


AUTO 
Enable/disable automatic line numbering 


AUTO [line#] 


This command turns on the automatic line-numbering feature. 
This eases the job of entering programs, by automatically typing 
the line numbers for the user. As each program line is entered by 
pressing RETURN, the next line number is printed on the screen, 
and the cursor is positioned on the second space to the right of 
the line number. The line number argument refers to the desired 
increment between line numbers. AUTO without an argument 
turns off the auto line numbering, as does RUN. This statement 
Can be used only in direct mode (outside of a program). 
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EXAMPLES: 


AUTO 10 Automatically numbers program lines in increments 
of 10. 


AUTO 50 Automatically numbers lines in increments of 50. 
AUTO Turns off automatic line numbering. 


BACKUP 


Copy the entire contents from one disk to another 
on a dual disk drive. 


BACKUP source Ddrive number TO destination Ddrive number 
[<ON | ,>Udevice] 


This command copies all the data from the source diskette onto 
the destination diskette using a dual disk drive. With the BACKUP 
command, a new diskette can be used without first formatting it. 
This is because the BACKUP command copies all the 
information on the diskette, including the format. Because of this, 
the BACKUP command destroys any information already on the 
destination disk. Therefore, when backing up onto a previously 
used diskette, make Sure it contains no programs you mean to 
keep. As a precaution the computer asks “ARE YOU SURE?” 
before it starts the operation. Press the “Y” key to perform the 
BACKUP, or any other key to stop it. You should always create a 
backup of all your disks, in case the original diskette is lost or 
damaged. Also see the COPY command. The default device 
number is unit 8. 


NOTE: This command can be used only with a dual-disk drive. It 
will not allow you to make copies of protected disks (most 
prepackaged software). 


EXAMPLES: 


BACKUP DO to D1 


Copies all data from the disk in drive 0 to the disk in drive 1, in 
dual disk drive unit 8. 
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BACKUP DO TO D1 ON U9 


Copies all data from drive 0 to drive 1, in disk drive unit 9. 


BANK 
Select one of the 16 banks, numbered 0-15 


BANK bank number 


This statement specifies the bank number and corresponding 
memory configuration for the Commodore 128 memory. The 
default bank is 15. Here is a table of available BANK 
configurations in the Commodore 128 memory: 


BANK CONFIGURATION 


0 RAM(O) only 

] RAM(1) only 

2 RAM(2) only* 

3 RAM(3) only* 

4 Internal ROM,RAM(0),I/O 

5 Internal ROM,RAM(1),I/O 

6 Internal ROM,RAM(2),|/O* 

7 Internal ROM,RAM(3),I/O* 

8 External ROM,RAM(0),|/O 

9 External ROM,RAM(1),I/O 

10 External ROM,RAM(2),|/O* 

11 External ROM,RAM(3),I/O* 

12 Kernal and Internal ROM(LOW),RAM(0),I/O 
13 Kernal and External ROM(LOW),RAM(0),I/O 
14 Kernal and BASIC ROM,RAM(0),Character ROM 
15 Kernal and BASIC ROM,RAM(0),1/O 


* For use on extended C1 28s with a larger internal memory eg: 
256K. In unexpanded machines there is no RAM in these BANKs 
and 2 echoes 0 and 3 echoes 1. 


To access a particular bank, type BANK n (n=0-15) and then use 
PEEK/POKE or SYS. From within the monitor, precede the four- 
digit hexadecimal number of the address range you are viewing 
with a hexadecimal digit (O-F) 
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BEGIN/BEND 


A structure used with IF...THEN ELSE so that you can include 
several program lines between the start (BEGIN) and end (BEND) 
of the structure. Here is the format: 


IF Condition THEN BEGIN : statement 


statement 

statement BEND : ELSE BEGIN 
statement 

statement BEND 


EXAMPLE: 


10 IF X=1 THEN BEGIN: PRINT “X=1 is True” 

20 PRINT “So this part of the statement is performed” 

30 PRINT “When X equals 1” 

40 BEND: PRINT “End of BEGIN/BEND structure”’:GOTO 60 
50 PRINT ‘‘X does not equal 1”:PRINT “The statements 
between BEGIN/BEND are skipped”’ 

60 PRINT ‘Rest of Program” 


If the Conditional (IF.. THEN) statement in line 10 is true, the 
Statements between the keywords BEGIN and BEND are 
performed, including all the statements on the same line as 
BEND. If the (IF.. THEN) conditional statement in line 10 is FALSE, 
all statements between the BEGIN and BEND, including the ones 
on the same program line as BEND are skipped, and the program 
resumes with the first program line immediately following the line 
containing BEND. The BEGIN/BEND essentially treats lines 10 
through 40 as one long line. 


The same rules are true if the ELSE:BEGIN clause is specified. If 
the condition is true all statements between ELSE:BEGIN and 
BEND are performed, including all statements on the same line 
as BEND. If False, the program resumes with the line immediately 
following the line containing BEND. 


BLOAD 
Load a binary file starting at the specified memory location 


BLOAD “‘filename’’[,Ddrive number] [CON | ,>Udevice 
number] [,Bbank number] [,Pstart address] 
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where: 


® filename is the name of your file 
@® bank number lets you select one of the 16 banks 
® start address is the memory location where loading begins 


A binary file is a file, whether a program or data that has been 
SAVEd either within the machine language monitor or the BSAVE 
command. The BLOAD command loads the binary file into the 
location specified by the start address. 


EXAMPLE: 


BLOAD “SPRITES”, BO, P3584 


LOADS the binary file “SPRITES” starting in location 3584 in 
BANK 0. 


BLOAD “DATA1”, DO, U8, B1, P4096 
LOADS the binary file “DATA 1” into location 4096 (BANK 1) 
from Drive 0, unit 8. 


lf start address is not specified the file will load at the same 
address it was saved from. 


BOOT 


Load and execute a program which was saved as a binary 
file. 


BOOT ["filename’”’] [,Ddrive number][<ON | ,>Udevice] 


The command loads an executable binary file and begins 
execution at the predefined starting address. The default device 
number is 8 drive 0. 


EXAMPLE: 


BOOT 


BOOT an executable program, (CP/M Plus for example). This is a 
special case and requires setting up a specific sector on the disk. 


BOOT’’GRAPHICS 1”,DO0, U9 


rere 


“GRAPHICS 1”, DO, U9 BOOTS the program “GRAPHICS 1” from 
unit 9, drive O and executes it. 

Execution begins at the start address of the program (ie where it 
Starts loading). 


BOX 
Draw box at specified position on screen 
BOX [color source],X1,Y1[,X2,Y2] [,angle] [,paint] 


where: 
color source O=Background color 
1=Foreground color 
2=Multicolor 1 Only in Graphics 
3=Multicolor 2 modes 3 and 4 
x1, y1 Top left corner coordinate (scaled) 
x2, y2 Bottom right corner opposite x1, y1, 
(scaled); default is the PC location. 
angle Rotation in clockwise degrees 
default is O degrees 
paint Paint shape with color 
O=Do not paint 
1=Paint 
(default=0) 


This statement allows the user to draw a rectangle of any size on 
the screen. Rotation is based on the centre of the rectangle. The 
pixel cursor (PC) is located at x2, y2 after the BOX statement is 
executed. The color source number must be a zero (QO) or one (1) 
if in standard bit map or a 2 or 3 if in multicolor bit map mode. 
Also see the GRAPHIC command for selecting the appropriate 
graphic mode to be used with the BOX color source number. 


Also see the LOCATE command for information on the pixel 
Cursor. 


EXAMPLES: 


BOX 1, 10, 10, 60, 60 
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Draws the outline of a rectangle. 


BOX 1, 10, 10, 60, 60, 45, 1 


Draws a painted, rotated box (a diamond). 


BOX , 30, 90, , 45, 1 
Draws a filled, rotated polygon. 


BOX 1, 20, 20,,,1 
Draws a filled rectangle from 20, 20 to the current pixel cursor. 


Any parameter can be omitted but you must include a comma in 
its place, as in the last two examples. 


NOTE: X2, Y2 count as one parameter so only one extra comma 
is required. Wrapping occurs if the degree is greater than 360 ie: 
360=0 (450=90). 


BSAVE 
Save a binary file from the specified memory locations 


BSAVE “‘filename’’[,Ddrive number] [,;<ON| ,>Udevice 
number] [,Bbank number]Pstart address TO Pend address 


where: 


@ filename is the name you give the file 

drive number is either 0 or 1 on a dual drive (0 is the default ) 
device number is the number of disk drive unit (default is 8) 
bank number is the number of the bank you specify (0-15) 

start address is the starting address where the program is 
SAVEd from end address -1 is the last address in memory which 
is SAVEd i.e. end address should be 1 byte higher than the last 
byte you wish to save 


This is the same as the SAVE command in the machine language 
MONITOR. 


EXAMPLE: 


BSAVE “SPRITE DATA”’,B0,P3584 to P4096 
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Saves the binary file named “SPRITE DATA” starting at location 
3584 through 4095 (BANK 0). 
BSAVE “*PROGRAM.SCR’’,DO,U9,B0,P3182 to P8000 


Saves the binary file named "PROGRAM.SCR’ in the memory 
address range 3182 through 7999 (BANK 0) on drive 0, unit 9. 


CATALOG 
Displays the disk directory. 


CATALOG [Ddrive number] [<ON | ,>Udevice number] 
[ wildcard string] 


The CATALOG command displays the directory on the specified 
drive just like the DIRECTORY command. See the DIRECTORY 
command for more examples (DIRECTORY and CATALOG are 
interchangeable). 

EXAMPLE: 


CATALOG Displays the disk directory on drive O of unit 8 


CHAR 


Displays characters at the specified position on the 
screen 


CHAR [color source ],x,y[,string] [,RVS] 


This is primarily designed to display characters on a bit mapped 
screen, but it can also be used on a text screen. Here's what the 
parameters mean: 


color source O=Background 
1=Foreground 
2=Multicolor 1 
3=Multicolor 2 
X Character column (0-79) (wraps around 
to the next line in 40-column mode) 
y Character row (0-24) 
string String to print 
reverse Reverse field flag (O=off, 1=on) 
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Text (alphanumeric strings) can be displayed on any screen ata 
given location by the CHAR statement. Character data is read 


from the Commodore 128 character ROM area. The user 


supplies the x and y coordinates of the starting position and the 
text string to be displayed. Color source and reverse imaging are 


optional. 


The string is continued on the next line if it attempts to print past 
the right hand edge of the screen. When used in TEXT mode, the 
string printed by the CHAR command works just like a PRINT 
string, including cursor and color control. These control functions 
inside the string do not work when the CHAR command is used 


to display text in bit map mode. Upper/Lower case controls 
(CHR$ (14) or CHR$ (142)) also operate in bit map mode. 


Multicolor characters are handled differently from standard 
Characters, the following table shows how to generate the 
possible combinations. 


Reverse Flag 


Color 0 Text 
Source Background 


Color 1 Text 
Source Background 


Color 2 Text 
Source Background 


Color 3 Text 
Source Background 





EXAMPLE : 


10 COLOR 2,3: REM multicolor 1=Red 
20 COLOR 3,7: REM multicolor 2=Blue 
30 GRAPHIC 3,1 

40 CHAR 0,10,10,’ TEXT’’,O 

50 CHAR 0,10,11,’’ TEXT’’,1 
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CIRCLE 


Draws circles, ellioses, arcs, etc. at specified positions on the 
screen 


CIRCLE [color source],X,Y,Xr [,Yr] [,sa] [,ea] [,angle] [,inc] 


where: 

color source O=background color 
1=foreground color 
eae GRAPHIC modes 
3=mulitcolor 3 and 4 

xy Centre coordinate of the CIRCLE 

xr X radius (scaled) 

yr Y radius (default is xr) 

sa Starting arc angle (default 0 degrees) 

ea Ending arc angle (default 360 degrees) 

angle Rotation in clockwise degrees (default is 
O degrees) 

inc Degrees between segments (default is 2 
degrees) 


Sa 


With the CIRCLE statement, the user can draw a circle, ellipse, 
arc, triangle, octagon or other polygon. The final pixel Cursor (PC) 
is left at the circumference of the circle at the ending arc angle. 
Any rotation is relative to the centre. Arcs are drawn from the 
starting angle clockwise to the ending angle. The increment 
controls the smoothness of the shape; using lower values results 
in more nearly circular shapes. Specifying the inc greater than 2 
creates a rough-edged boxed-in shape. 


Also see the LOCATE command for information on the pixel 
Cursor. 
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EXAMPLES: 

CIRCLE1, 160,100,65,10 Draws an ellipse 
CIRCLE1, 160,100,65 Draws a circle 
CIRCLE1, 60,40,20,18,,,,45 Draws an octagon 
CIRCLE1, 260,40,20,30,,,,.90 Draws a diamond 
CIRCLE1, 60,140,20,18,,,,120 Draws a triangle 


You may omit a parameter, but you must still place a comma in 
the appropriate position. Omitted parameters take on the default 
values. 


CLOSE 
Close logical file 
CLOSE file number 


This statement closes any files used by the DOPEN or OPEN 
statements. The number following the word CLOSE is the file 
number to be closed. 


EXAMPLE: 
CLOSE 2 Logical file 2 is closed. 


CLR 
Clear program variables 
CLR 


This statement erases any variables in memory, but leaves the 
program intact. This statement is automatically executed when a 
RUN or NEW command is given. 


CMD 
Redirect screen output 
CMD logical file number [, write list] 


This command sends the output, which normally goes to the 
screen (i.e., PRINT statement, LIST, but not POKES into the 
screen) to another device, such as a disk data file or printer. This 
device or file must be OPENed first. The CMD command must be 
followed by a number or numeric variable referring to the file. The 
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write list can be any alpha numeric string or variable. This 
command is useful for printing headings at the top of program 
listings. 

EXAMPLE: 

OPEN 1,4 OPENS device #4, which is the printer. 

CMD 1 All normal output now goes to the printer. 


LIST The LISTing goes to the printer, not the screen—even the 
word READY. 


PRINT#1 Sends output back to the screen. 
CLOSE 1 Closes the file. 


COLLECT 
Free inaccessible disk space 
COLLECT [Ddrive number] [<ON | ,>Udevice] 


Use this command to make available any disk space that has 
been allocated to improperly closed (splat) files, and to delete 
references to these files from the directory. Splat files are files 
that appear on the directory with an asterisk next to them. 
Defaults to device number 8. 


EXAMPLE: 


COLLECT DO 


Free all available space which has been incorrectly allocated to 
improperly closed files. 


NOTE: It will also free space allocated for direct access. See 
your disk drive manual for more information. 


COLLISION 
Define handling for sprite collision interrupt 
COLLISION type [,statement] 


type Type of interrupt as follows: 
1 = Sprite-to-sprite collision 
2 = Sprite-to-display data collision 
3 = Light pen 
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statement BASIC line number of a Subroutine 


When the specified situation occurs, BASIC will finish processing 
the currently executing instruction and perform a GOSUB to the 
line number given. When the subroutine terminates (it must end 
with a RETURN), BASIC will resume processing where it left off. 
Interrupt action continues until a COLLISION of the same type 
without a line number is specified. More than one type of interrupt 
may be enabled at the same time, but only one interrupt can be 
handled at a time (i.e., there can be no recursion and no nesting 
of interrupts). The cause of an interrupt may continue causing 
interrupts for some time unless the situation is altered or the 
interrupt disabled. 


To determine which sprites have collided since the last check, 
use the BUMP function. 


EXAMPLE: 


Collision 1, 5000 


Detects a sprite-to-sprite collision and program control sent to 
subroutine at line 5000. 


Collision 1 
Stops interrupt action which was initiated in above example. 


Collision 2, 1000 


Detects sprite-to-sprite collision and program control directed to 
Subroutine in line 1000. 


NOTE: Sprites can still collide even if they are off the screen, but 
not if they are switched off. 


COLOR 

Define colors for each screen area 

COLOR source number, color number 

This statement assigns a color to one of the seven color areas: 


Area Source 
0 40-column (VIC) background 
1 40-column (VIC) foreground 
2 multicolor 1 
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om & ®& 


Colors that are usable are in the range 1-16. 


Color Code 


ONO WP — 


CONOR WM — 


EXAMPLE: 


Color 0, 1: 


multicolor 2 


40-column (VIC) border 
character color (40- or 80-column screen) 
80-column background color 


Color 


Black 
White 
Red 
Cyan 
Purple 
Green 
Blue 
Yellow 


Black 

White 

Dark Red 
Light Cyan 
Light Purple 
Light Green 
Dark Blue 
Light Yellow 


Color Numbers in 40-Column Format 


Color Code Color 

° Orange 

10 Brown 

14 Light Red 

12 Dark Gray 

13 Medium Gray 
14 Light Green 
15 Light Blue 

16 Light Gray 

9 Dark Purple 
10 Brown 

11 Light Red 

le Dark Cyan 
13 Medium Gray 
14 Light Green 
15 Light Blue 

16 Light Gray 


Color Numbers in 80-Column Format 


Change background color of 40 column screen to black 


Color 5, 8: 


Change character color to yellow 


CONCAT 


Concatenates two gata files 
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CONCAT “‘file 2” [,Ddrive number] TO “file 1” 
[,Ddrive number] [<ON | ,>Udevice] 


The CONCAT command attaches file 2 to the end of file 1 and 
retains the name of file 1. The device number defaults to 8 and 
the drive number defaults to 0. 


EXAMPLE: 


Concat ‘‘File B’’ to ‘File A”’ 


FILE B is attached to FILE A and the combined file is designated 
FILEA 


Concat (A$) to (B$), D1, US 


The file named by B$ becomes a new file of the same name with 
the file named by A$ attached to the end of B$ — This Is 
performed on Unit 9, drive 1 (a dual disk drive). 


Whenever a variable is used as a filename as in the last example, 
the filename variable must be surrounded by parentheses. 


NOTE: Keep the filenames short (10 characters) because the 
command buffer is limited in some disk drives. 


CONT 
Continue program execution 
CONT 


This command is used to restart a program that has been 
stopped by either using the STOP key, a STOP statement, or an 
END statement. The program resumes execution where it left off. 
CONT will not resume with the program if lines have been 
Changed or added to the program or if any editing of the program 
is performed on the screen. If the program stopped due to an 
error; or if you have caused an error before trying to restart the 
program CONT will not work. The error message in this case is 
CAN'T CONTINUE ERROR. 
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COPY 


Copy files from one drive to another in a dual disk 
drive or within a single drive. 


COPY <([‘‘source filename’’] [,Ddrive number] >TO< 
[‘‘destinationfilename’’] [,Ddrive number]> [<ON| ,>Udevice] 


This command copies files from one disk (the source file) to 
another (the destination file) on a dual-disk drive. It can also 
create a copy of a file on the same disk within a single drive, but 
the filename must be different. When copying from one drive to 
another, the filename may be the same. 


The COPY command can also COPY all the files from one drive 
to another on a dual disk drive. In this case the drive numbers are 
specified and the source and destination filenames are omitted. 


The default parameters for the COPY command are device 
number 8, drive 0. 


Note: Copying between two single or double disk drive units 
Cannot be done. See BACKUP. 


EXAMPLES: 


COPY ‘test’ ,DO TO “test prog”’,D1 


Copies “test” from drive 0 to drive 1, renaming it ‘test prog’ on 
drive 1. 


COPY “stuff” ,DO TO “‘stuff’’,D1 


Copies ‘‘stuff’ from drive 0 to drive 1. 


COPY DO TO D1 


Copies all files from drive 0 to drive 1. 


COPY “work.prog” TO “backup” 


Copies ‘work.prog’ as a file called “backup” on the same disk 
(drive O). 
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DATA 
Define data to be used by a program 
DATA list of constants 


This statement is followed by a list of data items to be input into 
the computer's memory by READ statements. The items may be 
numeric or string and are separated by commas. String data 
need not be inside quote marks, unless they contain any of the 
following characters: SPACE, colon, or comma. If two commas 
have nothing between them, the value is READ as a zero if 
numeric or as an empty string. Also see the RESTORE statement, 
which allows the Commodore 128 to reREAD data. 


EXAMPLE: 
DATA 100, 200, FRED, “HELLO MUM”, , 3, 14, ABC123 


DCLEAR 
Clear all open channels on disk drive 
DCLEAR [Ddrive number] [<ON | ,>Udevice] 


This statement closes and clears all open channels on the 
specified device number. Default is U8. This command is 
analagous to OPEN 0,8,15, “l0” CLOSE 0. 


EXAMPLE: 


DCLEAR DO 


Clears all open channels on drive 0, device number 8. 


DCLEAR D1,U9 
Clears all open channels on drive 1, device number 9. 


NOTE: Files will be aborted, data may not be recoverable from 
files which were being written to. See CLOSE/DCLOSE. 


DCLOSE 
Close disk file 
DCLOSE [#logical file number] [<ON | ,>Udevice] 
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This statement closes a single file or all the files currently open 
on a disk unit. If no logical file number is specified, all currently 
open files are closed. The default device number is 8. Note the 
following examples: 


EXAMPLES: 


DCLOSE 


Closes all files currently open on unit 8. 


DCLOSE #2 


Closes the file associated with the logical file number 2. 


DCLOSE ON U9 


Closes all files currently open on unit 9. 


DEF FN 
Return the value of a user-defined function 
DEF FN name (variable) = expression 


This statement allows definition of a complex calculation as a 
function. In the case of a long formula that is used several times 
within a program, this keyword can save valuable program space. 
The name given to the function begins with the letters FN, 
followed by any legal numeric variable name (not integer or 
array). First, define the function by using the statement DEF, 
followed by the name given to the function. Following the name is 
a set of parentheses () with a local numeric variable name 
enclosed. This variable only has a value if it appears in the 
expression to the right of the equals sign. The same variable 
name can be used elsewhere in a program but it will be 
completely separate from its use in the function. Other variables 
and/or functions can be used in the expression and these are 
evaluated as their value at the time the function is called. Next is 
an equal sign, followed by the formula to be defined. The function 
can be performed by substituting any number for X, using the 
format shown in lines 40 and 50 of the example below: 


fe20 


EXAMPLE: 


10 DEF FNEG(LO)=INT((V1*LO* 2)*100)/100 
LO IS LOCAL TO THIS LINE 
20 LO=15 
A NORMAL PROGRAM VARIABLE 
30 V1=3.14159 
APPROX PI 
40 PRINT FNEG(5) 
ASSIGN 5 TO THE LOCAL VALUE LO IN THE FUNCTION 
50 PRINT FNEG(1) 
USE 1 IN THE FUNCTION INSTEAD OF LO 
60 PRINT INT((V1*LO7 2)*100/100 
VARIABLE LO USED 
70 PRINT LO 
REMAINS UNCHANGED 


DELETE 


Delete lines of a BASIC program in the specified 
range. 


DELETE<(start line] [start line-]|[start line - end line]|[-end 
line]> 


This command can be executed only in direct mode. 
EXAMPLES: 


DELETE 75 


Deletes line 75. 


DELETE 10-50 
Deletes lines 10 through 50, inclusive. 


DELETE-50 


Deletes all lines from the beginning of the program up to and 
including line 50. 


DELETE 75- 


Deletes all lines from 75 to the end of the program, inclusive. 
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DIM 
Declare number of elements in an array 
DIM variable (subscripts) [,variable(subscripts)][...] 


Before arrays of variables can be used, the program must first 
execute a DIM statement to establish DIMensions of the array 
(unless there are 11 or fewer elements in each DIMension of the 
array). The DIM statement is followed by the name of the array, 
which may be any legal variable name. Then, enclosed in 
parentheses, the number (or numeric variable) of elements in 
each dimension. An array with more than one dimension is called 
a matrix. Any number of dimensions may be used, but keep in 
mind the whole list of variables being created takes up space in 
memory, and it is easy to run out of memory if too many are used. 
Here’s how to calculate the amount of memory used by an array: 


5 bytes for the array name 

2 bytes for each dimension 

2 bytes/elements for integer variables 

5 bytes/elements for normal numeric variables 
3 bytes/elements for string variables 

1 byte for each character in each string element 


Integer arrays take up two-fifths the space of floating-point arrays 
(e.g., DIM A% (100) requires 209 bytes; DIM A (100) requires 512 
bytes.) 


NOTE: Elements are numbered from 0 eg DIM A(100) gives 101 
elements. 

More than one array can be dimensioned in a DIM statement by 
separating the array variable name by commas. If the program 
executes a DIM statement for any array more than once, the 
message “RE’DIM ARRAY ERROR’ is posted. It is good 
programming practice to place DIM statements near the 
beginning of the program. 


EXAMPLE: 
10 DIM A$(40),B7(15),CC%(4,4,4) 
41 elements, 16 elements, 125 elements 


17-22 


DIRECTORY 
Displays the contents of the disk directory on the screen. 
DIRECTORY [Ddrive number] [<ON | ,>Udevice] [,wildcard] 


The F3 function key in C128 mode displays the DIRECTORY for 
device number 8, drive 0. Use CONTROL S or NO SCROLL to 
pause the display; any key restarts the display after a pause. Use 
the COMMODORE key to slow down the display. The 
DIRECTORY command should not be used to print a hard copy 
because some printers interfere with the data coming from the 
disk drive. The disk directory should be loaded (LOAD"$"'8) 
destroying the program Currently in memory in order to print a 
hard copy. The default device number is 8, and the default drive 
number is 0. 


EXAMPLES: 


DIRECTORY 


Lists all files on the disks in unit 8. 


DIRECTORY D1, U9, ““WORK’”’ 
Lists the file named WORK" on drive 1 of unit 9. 


DIRECTORY “AB*” 


Lists all files starting with the letters “AB” like ABOVE, ABOARD, 
etc. on all drives of unit 8. The asterisk specifies a wild card, 
where all files starting with “AB” are displayed. 


DIRECTORY DO, ‘FILE ?.BAK”’ 


The ? is a wild card that matches any single character in that 
position. For example: FILE 1.BAK, FILE 2.BAK, FILE 3.BAK all 
match the string. 


DIRECTORY D1,U9,(A$) 


LISTS the filename stored in the variable A$, on device number 9, 
drive 1. Remember whenever a variable is used as a filename, 
surround the variable in parentheses. 
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NOTE: To print the DIRECTORY of the disk in drive 0, unit 8, use 
the following example: 


LOAD“$0”’’,8 
OPEN4,4:CMD4:LIST 
PRINT#4:CLOSE4 


DLOAD 
Load a BASIC program from disk 


DLOAD ‘‘filename”’ [,Ddrive number] [CON | ,>Udevice 
number] 


This command loads a BASIC program from disk into current 
memory. (Use LOAD to load programs from tape.) The program 
must be specified by a filename of up to 16 characters. DLOAD 
assumes device number 8, drive 0. 


EXAMPLES: 


DLOAD “BANKRECS” 
Searches the disk for the program “BANKRECS” and LOADs tt. 


DLOAD (A$) 


LOADS a program from disk whose name is stored in the variable 
A$. An error message Is given if A$ is empty. Remember, when a 
variable is used as filename, it must be enclosed in parentheses. 


The DLOAD command can be used within a BASIC program to 
find another program on disk. This is called chaining. 


DO/LOOP/WHILE/UNTIL/EXIT 
Define and control program loop 


DO [UNTIL condition | WHILE condition] statements [EXIT] 
LOOP [UNTIL condition | WHILE condition] 
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This loop structure performs the statements between the DO 
statement and the LOOP statement. If no UNTIL or WHILE 
modifies either the DO or the LOOP statement, execution of the 
statements in between continues indefinitely. If an EXIT 
statement is encountered in the body of a DO loop, execution is 
transferred to the first statement following the LOOP statement. 
DO loops may be nested, following the rules defined by the FOR- 
NEXT structure. If the UNTIL parameter is specified, the program 
continues looping until the condition is satisfied (becomes true). 
The WHILE parameter is basically the opposite of the UNTIL 
parameter: the program continues looping as long as the 
condition is TRUE. As soon as the condition is no longer true, 
program control resumes with the statement immediately 
following the LOOP statement. An example of a condition 
(boolean argument) is A=1, or G>65. 


EXAMPLE: 


10 X=25 

20 DO UNTIL X=0 

30 X=X-1 

40 Print ‘‘X="’;X 

50 LOOP 

60 PRINT “End of Loop” 


This example performs the statements X=X-1 and Print “X=";X 
until X=0. When X=0 the program resumes with the statement 
immediately following LOOP, PRINT “End of Loop”. 


10 DO WHILE A$=“*”:GET A$:LOOP 
20 PRINT “THE “;A$;’” KEY HAS BEEN PRESSED” 


A$ remains null as long as no key is pressed. As soon as a key is 
pressed program control passes to the statement immediately 
following LOOP, PRINT “THE’;A$; “KEY HAS BEEN PRESSED”. 
The example performs GET A$ as long as A$ is a null character. 
This loop constantly checks to see if a key on the keyboard is 
being pressed. Note GETKEY A$ has the same effect as line 10. 


10 DOPEN #8,“SEQFILE” 
20 DO 

30 GET #8,A$ 

40 PRINT A$; 

50 LOOP UNTIL ST 

60 DCLOSE #8 
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This program opens file “SEQFILE” and gets data until the ST 
system variable indicates all data is input. A value of 0 indicates a 
FALSE condition, nonzero is true. ST is normally 0. 


DOPEN 
Open a disk file for a read and/or write operation. 


DOPEN #logical file number,’’filename[,<S|P>]’’[,Lrecord 
length] [,Ddrive number] [<ON | ,>Udevice number] [,w] 


where: 


S = Sequential File Type 

P = Program File Type 

L = record length = the length of records in a relative file only 
W = Write Operation (if not specified a read operation occurs) 


This statement opens a sequential, program or relative file for a 
read or write operation. The record length (L) pertains to a 
relative file, which can be as long as 254. The “W” parameter Is 
specified only during a write (PRINT #) operation in a sequential 
file. If it is not specified, the disk drive assumes the disk operation 
to be a READ operation. Relative files are open for both READ 
and WRITE operations at the same time. 


The logical file number associates a number to the file for future 
disk Operations such as a read (input #) or write (print #) 
operation. The logical file number can range from 1 to 255. 
Logical file numbers greater than 128 automatically send a 
Carriage return and linefeed with each write (print #) command. 
Logical file numbers less than 128 send only a carriage RETURN, 
which can be suppressed with a semi-colon at the end of the 
print # command. The default device number is 8, and the default 
drive is 0. 


EXAMPLES: 


DOPEN#1, “ADDRESS’’,W 


Open the sequential file number 1 (ADDRESS) for a write 
operation. 
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DOPEN#2, “RECIPES’”’,D1,U9 

Open the sequential file number 2 (RECIPES) for a read operation 
on device number 9, drive 1. 

DOPEN#3,“BOOKS’”,L128 


Open the relative file number 3 (BOOKS) for READ or WRITE on 
unit 8 drive 0. Record length is 128 characters. 


DRAW 


Draw dots, lines and shapes at specified positions on 
screen 


DRAW [color source],X1,Y1[TO X2, Y2]... 


This statement draws individual dots, lines, and shapes. Here are 
the parameter values: 


Color source = 0 Bit map background 
1 Bit map foreground 
2 Multicolor 1 GRAPHICS modes 
3 Multicolor 2 3 and 4 

X1,Y1 Starting coordinate, scaled 

X2,Y2 Ending coordinate, scaled 


Also see the LOCATE command for information on the pixel 
Cursor 


EXAMPLES: 

DRAW 1, 100, 50 Draw a dot 

DRAW , 10,10 TO 100,60 Draw a line 

DRAW , 10,10 TO 10,60 TO 100,60 TO 10,10 Draw a triangle 


You may omit a parameter but you still must include the comma 
that would have followed the unspecified parameter. 


DSAVE 


Save a BASIC program file to disk 
DSAVE ‘“‘filename” [,Ddrive number] [<ON | ,>Udevice number] 
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This command stores (SAVEs) a BASIC program on disk. (See 
SAVE to store programs on tape.) A filename up to 16 characters 
long must be supplied. The default device number is 8, while the 
default drive number is 0. 


EXAMPLES: 


DSAVE ‘“‘BANKRECS” 
SAVEs the program “BANKRECS" to disk. 


DSAVE (A$) 
SAVEs the disk program named in the variable A$. 


DSAVE “PROG 3’’,D1,U9 


SAVEs the program “PROG 3” to disk on unit number 9, drive 1. 
(On a dual drive unit). 


DVERIFY 
Verify the program in memory against the one on disk 


DVERIFY “‘filename’’[,Ddrive number] [<ON| ,>Udevice 
number] 


This command causes the Commodore 128 to check the 
program on the specified drive against the program in memory. 
The default drive number is 0 and the default device number Is 8. 


NOTE: If a graphic area is allocated or deallocated after a SAVE, 
an error occurs. Technically this is correct. Because BASIC text 
is moved from its original (SAVEd) location when a bit mapped 
graphics area Is allocated or deallocated, the original location 
where the C128 verified the SAVEd program changes. Hence, 
VERIFY, which performs byte-to-byte comparisons, fails, even 
though the program is valid. 


To verify Binary data, see VERIFY ‘‘filename’’,8,1 format, under 
VERIFY command description. 


EXAMPLES: 
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DVERIFY “C128” 
Verifies program C128” on drive 0, unit 8. 


DVERITY “SPRITES’’,D0,U9 
Verifies program “SPRITES” on drive 0, device 9. 


END 
Define the end of program execution. 
END 


When the program encounters the END statement, it stops 
RUNning immediately. The CONT command can be used to 
restart the program at the next statement (if any) following the 
END statement. 


ENVELOPE 
Define a musical instrument envelope 
ENVELOPE n{,atk] [,dec] [,sus] [,rel] [, wf] [,pw ] 


where: 
n Envelope number (0-9) 
atk Attack rate (0-15) 
dec Decay rate (0-15) 
sus Sustain rate (0-15) 
rel Release rate (0-15) 
wt Waveform: 0 = triangle 
1 = sawtooth 
2 = variable pulse (Square) 
3 = noise 
4 = ring modulation 
pw Pulse width (0-4095) 


A parameter that is not specified will retain its predefined or 
Currently redefined value. Pulse width applies to the width of the 
variable pulse waveform (wf=2) only and is determined by the 
formula pwout = pw/40.95, so that pw = 2048 produces a 
Square wave and values of 0 and 4095 produce constant DC 
Output. The Commodore 128 has initialized the following 10 
envelopes: 
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n A D S R- wf pw instrument 
ENVELOPE 0, O, 9, O, O, 2, 1586 piano 
ENVELOPE 71, 2, Of 172,°-0, 1 accordion 
ENVELOPE 2, 0, O, 15, 0, 0 calliope 
ENVELOPE «& -0: & & @. 3 drum 
ENVELOPE 4, 9, 4, 4, O, O flute 
ENVELOPE 5, ODO, 9, 2 1; 7 guitar 
ENVELOPE 6, 0O, 9, O, O, 2, 512 harpsichord 
ENVELOPE 7, 0, 9, 9, O, 2, 2048 organ 
ENVELOPE 8, 8 9, 4, 1, 2, 512 — trumpet 
ENVELOPE 9, 0O, 9, O, O, O xylophone 


To play predefined musical instrument envelopes, you simply 
specify the envelope number in the PLAY command (see PLAY) 
you do not need to use the ENVELOPE command. The 
ENVELOPE command is used only when you need to change the 
envelope. 


FAST 
Put machine in 2 MHz mode of operation 
FAST 


This command initiates 2MHz mode, causing VIC 40 column 
screen to be turned off. All operations (except |/O) are speeded 
up considerably. Graphics may be used, but will not be visible 
until a SLOW command is issued. 


FETCH 
Get data from expansion (RAM module) memory 


FETCH #bytes, intsa, expsa, expb 


where bytes = number of bytes to get from expansion 
memory (0-65535) 

intsa = starting address of host ram (0-65535) 

expsa = Starting address of expansion ram (0-65535) 

expb = 64k expansion RAM bank number (0-15) 
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FILTER 
Define sound (SID chip) filter parameters 
FILTER [freq] [,Ip] [,bp] [,hp] [,res] 


where: 
freq Filter Cut-off frequency (0-2047) 
Ip Low-pass filter on (1), off (0) 
bp Bank-pass filter on (1), off (0) 
hp High-pass filter on (1), off (0) 
res Resonance (0-15) 


Unspecified parameters result in no change to the current value. 


You can use more than one type of filter at a time. For example, 
both low-pass and high-pass filters can be used together to 
produce a notch-(or band-reject) filter response. For the filter to 
have an audible effect, at least one type of filter must be selected 
and at least one voice must be routed through the filter. 


EXAMPLE: 


FILTER 1024,0,1,0,2 

Set the cutoff frequency at 1024, select the band pass filter and a 
resonance level of 2. 

FILTER 2000,1,0,1,10 


Set the cutoff frequency at 2000, select both the low pass and 
high pass filters (to form a notch-reject) and set the resonance 
level at 10. 


FOR/TO/STEP/NEXT 
Define a repetitive program loop structure. 
FOR variable = start value TO end value [STEP increment] 


This statement works with the NEXT statement to set up a 
section of the program that repeats for a set number of times (1.e., 
a loop). This is useful when something needs to be counted or 
something must be done a certain number of times (such as 


printing). 
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This statement executes all the commands enclosed between 
the FOR and NEXT statements repetitively, according to the start 
and end values. The start value and the end value are the 
beginning and ending counts for the loop variable. The loop 
variable is added to or subtracted from during the FOR/NEXT 
loop. 


The logic of the FOR/NEXT statement is as follows. First, the loop 
variable is set to the start value. When the program reaches a 
program line containing the NEXT statement, it adds the STEP 
increment (default = 1) to the value of the loop variable and 
checks to see if it is higher than the end value of the loop. If the 
loop variable is less than or equal to the end value, the loop is 
executed again, starting with the statement immediately following 
the FOR statement. If the loop variable is greater than the end 
value, the loop terminates and the program resumes immediately 
following the NEXT statement. The opposite Is true if the step size 
is negative. 


EXAMPLE A: EXAMPLE B: 

10 FORL=1T0O 10 10 FOR L=10 TO 1 STEP -1 
20 PRINT L 20 PRINT L 

30 NEXT L 30 NEXT L 


40 PRINT “I’M DONE! L = ”’;L 40 PRINT “I’M DONE! L = ”3L 


Program A prints the numbers from one to 10 followed by the 
message I'M DONE! L = 11. Program B prints the numbers down 
to one and then |'M DONE! L = 0 


The end value of the loop may be followed by the word STEP and 
another number or variable. In this case, the value following the 
STEP is added each time instead of one. This allows counting 
backwards, by fractions, or in increments other than one. 


The user can set up loops inside one another. These are known 
as nested loops. Care must be taken when nesting loops so the 
last loop to start Is the first one to end. 


EXAMPLE: 


10 FOR L=1 TO 100 

20 FOR A=57T011 STEP .5 
30 NEXT A 

40 NEXT L 
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The FOR ... NEXT loop in lines 20 and 30 are nested inside the 
one in line 10 and 40. Using a STEP increment of .5 is used to 
illustrate the fact that floating point indices are valid. 

See also the NEXT statement. 


GET 


Receive input data from the keyboard, one character 
at a time without waiting for a key to be pressed. 


GET variable list 


The GET statement reads each key typed by the user. As the 
user types, the characters are stored in the computers memory 
(in an area called the keyboard buffer). Up to 10 characters can 
be stored here, any characters typed after the 10th are lost. The 
GET statement reads the first character from the buffer and 
moves the rest up allowing room for more. If there are no 
Characters in the buffer a null (empty) character is returned. The 
word GET is followed by a variable name, either numeric or 
string. GET will not pause the program if no characters are in the 
buffer (see GETKEY). 


If the C128 intends to GET a numeric key and a key other than a 
number is pressed the program stops and a TYPE MISMATCH 
error message Is displayed. The GET statement may also be put 
into a loop, checking for an empty result. The GETKEY statement 
could also be used in this case. See GETKEY for more 
information. The GET and GETKEY statements can be executed 
only within a program. 


EXAMPLE: 

10 DO:GETA$:LOOP UNTIL A$=“A” 

This line waits for the A key to be pressed to continue. 
20 GET B, C, D 


GET numeric variables B, C and D from the keyboard without 
waiting for a key to be pressed. 
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GETKEY 


Receive input data from the keyboard, one character 
at a time and wait for a key to be pressed. 


GETKEY variable list 


The GETKEY statement is very similar to the GET statement. 
Unlike the GET statement, GETKEY if there is no character in the 
keyboard buffer will wait for the user to type a character on the 
keyboard. This lets the computer wait for a single character to be 
typed. This statement can be executed only within a program. 


EXAMPLE: 
10 GETKEY A$ 


This line waits for a key to be pressed. Typing any key continues 
the program. 


10 GETKEY A$,B$,C$ 


This line waits for three alphanumeric characters to be entered 
from the keyboard. GETKEY can also be used to READ numeric 
keys. 


NOTE: GETKEY cannot return a null (empty) character 
String. 


GET# 
Receive input data from a tape, disk or RS232 
GET# file number, variable list 


This statement inputs one character at a time from a previously 
opened file. Otherwise, it works like the GET statement. This 
Statement can be executed only within a program. 


EXAMPLE: 


10 GET#1,A$ 


This example receives one character, which is stored in the 
variable A$, from file number 1. This example assumes that file 1 
was previously opened. See the OPEN and DOPEN statements. 
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GO64 
Switch to C64 mode 


GO64 


This statement switches from C128 mode to C64 mode. The 
question “Are You Sure?” is displayed in response to the GO64 
statement. If Y is typed, then the currently loaded program is lost 
and control is given to C64 mode; otherwise, if any other key is 
pressed, the computer remains in C128 mode. This statement 
can be used in direct mode or within a program. The prompt is 
not displayed in program mode. 


GOSUB 
Call a subroutine from the specified line number. 
GOSUB line number 


This statement is similar to the GOTO statement, except the 
Commodore 128 returns from where it came when the subroutine 
is finished. When a line with a RETURN statement is 
encountered, the program jumps back to the statement 
immediately following the GOSUB statement. 


The target of a GOSUB statement is called a subroutine. A 
subroutine is useful if a task is repeated several times within a 
program. Instead of duplicating the section of program over and 
Over, set up a Subroutine, and GOSUB to it at the appropriate 
time in the program. See also the RETURN statement. 


EXAMPLE: 


20 GOSUB 800 


799 END 
800 PRINT “HI THERE”: RETURN 


This example calls the subroutine beginning at line 800 and 
executes it. All subroutines must terminate with a RETURN 
statement. 

Line 799 stops the program accidentally falling through into the 
subroutine. 
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GOTO/GO TO 
Transfer program execution to the specified line number 
GOTO line number 


After a GOTO statement is encountered in a program, the 
computer executes the statement specified by the line number in 
the GOTO statement. When used in direct mode, GOTO 
executes (RUNs) the program starting at the specified line 
number without clearing the variables. This is the same as the 
RUN command except it does not clear variable values. 


EXAMPLES: 


10 PRINT‘'COMMODORE’”’ 
20 GOTO 10 


The GOTO in line 20 makes line 10 repeat continuously until 
RUN/STOP is pressed. 


GOTO 100 


Starts (RUNs) the program starting at line 100, without clearing 
the variable storage area. 


GRAPHIC 
select a graphic mode 


1) GRAPHIC mode [,clear] [,s] or 
2) GRAPHIC CLR 


This statement puts the Commodore 128 in one of the six 
graphic modes: 


mode description 


40-column text 

standard bit-map graphics 

standard bit-map graphics (split screen) 
multicolor bit-map graphics 

multicolor bit-map graphics (split screen) 
80-column text 


mm GN =| © 
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The clear parameter specifies whether the bit mapped screen is 
cleared (equal to 1) upon running the program, or left intact 
(equal to 0). The s parameter indicates the starting line number of 
the split screen when in graphic mode 2 or 4 (multicolor or 
standard bit map split screen modes). The default starting line 
number of the split screen is 19. 


When executed, GRAPHIC 1-4 allocates a 9K-bit mapped area. 
The start of BASIC text area is moved above the bit-map area, 
and any BASIC program is automatically relocated. This area 
remains allocated even if the user returns to TEXT mode 
(GRAPHIC 0). If the clear option is specified as 1, the screen Is 
cleared. The GRAPHIC CLR command deallocates the 9k, bit 
mapped area making it available once again for BASIC text. Any 
BASIC program is relocated. 


EXAMPLES: 


GRAPHIC 1,1 
Select standard bit map mode and clear the bit map. 


GRAPHIC 4,0,10 


select split screen multicolor bit map mode, do not clear the bit 
map and start the split screen at line 10. 


GRAPHIC 0 


Select 40 column text. 


GRAPHIC 5 


Select 80 column text. 


GRAPHIC CLR 
Clear and deallocate the bit map screen. 


HEADER 
Formats a diskette 


HEADER “‘diskname’’ [,| i.d.] [,Ddrive number] 
[<ON| ,>Udevice number] 
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where: 
diskname - any name up to 16 characters 


i.d. - any two alphanumeric characters. You must use two - you 
may not leave a space. 


Before a new disk can be used for the first time, it must be 
formatted with the HEADER command. The HEADER command 
can also be used to erase a previously formatted disk, which can 
then be reused. 


When you enter a HEADER command in direct mode, the prompt 
ARE YOU SURE? appears. In program mode, the prompt does 
not appear. 


This command divides the disk into sections called blocks. It 
creates a table of contents of files, called a directory. Give each 
disk a unique i.d. number. Be careful when using the HEADER 
command because it erases all stored data. 


You can HEADER a diskette more quickly if it was already 
formatted, by omitting the new disk i.d. The old i.d. is used. The 
quick header can be used only if the disk was previously 
formatted, since it clears out the directory rather than formatting 
the disk. The default device number is 8 and the default drive is 0. 


As a precaution, the system asks “ARE YOU SURE?” before the 


Commodore 128 completes the operation. Press the “Y”' key to 
perform the HEADER, or press any other key to cancel it. 


The HEADER command reads the disk command error channel, 
and if an error is encountered, the error message “?BAD DISK" is 
displayed. 

The HEADER command is analogous to the BASIC 2.0 
command: 

OPEN 1,8,15,”NO:diskname,i.d.” 

EXAMPLES: 

HEADER “MYDISK”’, 151, DO 
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This HEADERs “MYDISK” using i.d 51 on drive 0, (default) device 
number 8. 


HEADER “RECS”, 145, D1, ON U9 
This HEADERs “RECS” using i.d 45, on Drive 1, device number 9. 


HEADER ‘C128 PROGRAMS”, DO 


This is a quick header on drive 0, device number 8, assuming the 
disk in the drive was already formatted. The old i.d. is used. 


NOTE: you cannot use a variable string for the i.d. 


HELP 
Highlight the line where the error occurred 
HELP 


The HELP command is used after an error has been reported ina 
program. When HELP is typed in 40-column format, the line 
where the error occurs is listed, with the portion containing the 
error displayed in reverse field. In 80-column format, the portion 
of the line where the error occurs is underlined. Pressing the 
HELP key types HELP <RETURN> automatically. 


IF/THEN/ELSE 


Evaluate a conditional expression and execute portions of a 
program depending on the outcome of the expression. 


IF expression THEN statements BASIC 2.0 
IF expression THEN statements [:ELSE else-clause] BASIC 7.0 


The IF...THEN statement evaluates a BASIC expression and 
takes One of two possible courses of action depending upon the 
outcome of the expression. If the expression is true, the 
statement(s) following THEN is executed. This can be any BASIC 
statement. If the expression is false, the program resumes with 
the program line immediately following the program line 
containing the IF statement, unless an ELSE clause is present. 
The entire IF... THEN statement must be contained within 160 
characters (80 in C64 mode). Also see BEGIN/ BEND. 
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The ELSE clause, if present, must be on the same line as the 

IF... THEN portion of the statement, and separated from the THEN 
Clause by a colon. When an ELSE clause Is present, it is 
executed only when the expression is false. The expression 
being evaluated may be a variable or formula, in which case It is 
considered true if nonzero, and false if zero. In most cases, there 
is an expression involving relational operators (=,<,>,<=,> 
= <>). 


The IF...THEN statement can take two alternate forms: 


IF expression THEN line number 
or 
IF expression GOTO line number 


These forms transfer program execution to the specified line 
number if the expression Is true. Otherwise, the program resumes 
with the program line number immediately following the line 
containing the IF statement. 


EXAMPLE: 
50 IF X > 0 THEN PRINT ‘‘OK”: ELSE END 


This line checks the value of X. If X is greater than 0, the 
statement immediately following the keyword THEN (PRINT 
“OK") is executed and the ELSE clause is ignored. If X is less 
than or equal to 0, the ELSE clause is executed and the 
statement immediately following THEN Is ignored. 


10 IF X=10 THEN 100 
20 PRINT‘X does not equal 10” 


99 STOP 
100 PRINT ‘‘X equals 10” 


This example evaluates the value of X. IF X equals 10, the 
program control is transferred to line 100 and the message ''X 
EQUALS 10” is printed. IF X does not equal 10, the program 
resumes with line 20, the C128 prints the prompt “X does not 
equal 10” and the program stops. 

NOTE: The ELSE extension cannot be used in C64 mode. 
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INPUT 


Receive a data string or a number from the keyboard and wait for 
the user to press RETURN. 


INPUT [“‘prompt string’’;] variable list 


The INPUT statement asks for data from the user while the 
program is RUNning and places the data into a variable or 
variables. The program stops, prints a question mark (?) on the 
screen, and waits for the user to type the answer and hit the 
RETURN key. The word INPUT is followed by a prompt string and 
a variable name or list of variable names separated by commas. 
The message in the prompt string inside quotes suggests 
(prompts) the information the user should enter. If this message is 
present, there must be a semicolon (;) after the closing quote of 
the prompt. 


When more than one variable is INPUT, separate them by 
commas. The computer asks for the remaining values by printing 
two question marks (?7). If the RETURN key is pressed without 
INPUTing a value, the INPUT variable retains its previous value. 
The INPUT statement can be executed only within a program. 


EXAMPLE: 


10 INPUT “PLEASE TYPE A NUMBER’”;A 
20 INPUT ‘‘AND YOUR NAME” ;A$ 
30 PRINT A$;“‘YOU TYPED THE NUMBER’”;A 


INPUT# 
Inputs data from a file into the computer’s memory 
INPUT file number, variable list 


This statement works like INPUT, but takes the data from a 
previously OPENed file usually on a disk or tape instead of the 
keyboard. No prompt string is used. This statement can be used 
only within a program. 


EXAMPLE: 


10 OPEN 2,8,2,“DATAFILE,S,R” 
20 INPUT#2, A$, C, D$ 
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This statement INPUTs the data from the file DATAFILE and 
stores It in variables A$, C and D$. 


KEY 
Define or list function key assignments 
KEY [key number, string] 


There are eight function keys (F1-F8) available to the user on the 
Commodore 128: four unshifted and four shifted. The 
Commodore 128 allows you to perform a function or operation for 
each time the specified function key is pressed. The definition 
assigned to a key can consist of data, or a command or series of 
commands. KEY with no parameters specified returns a listing 
displaying all current KEY assignments. If data is assigned to a 
function key, that data is displayed on the screen when that 
function key is pressed. The maximum length for all the 
definitions together is 246 characters. 


EXAMPLE: 
KEY 7, ‘“GRAPHICO” + CHR$(13) + “LIST” + CHR$(13) 


This tells the computer to select the (VIC), 40 column, text screen 
and list the program whenever the F7 key Is pressed (in direct 
mode). CHR$(13) is the ASCII character for RETURN and 
performs the same action as pressing the RETURN key. Use 
CHR$(27) for ESCape. Use CHR$(34) to incorporate the double 
quote character into a KEY string. The keys may be redefined In 
a program. For example: 


10 KEY 2,“PRINT DS$” + CHR$(13) 


This tells the computer to check and display the disk drive error 
channel variable (PRINT DS$) each time the F2 function key is 
pressed. 


To restore all function keys to their BASIC default values, reset 
the Commodore 128 by pressing the RESET button. 


LET 
Assigns a value to a variable 


[LET] variable = expression 
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The word LET is rarely used in programs, since it is not 
necessary. Whenever a variable is defined or given a value, LET 
is always implied. The variable name that receives the result of a 
calculation is on the left side of the equal sign. The number, string 
or formula is on the right side. You can only assign one value with 
each (implied) LET statement. For example, LET A = B = 2 is not 
(normally) legal. 


EXAMPLE: 


10 LETA=5 
Assign the value 5 to numeric variable A. 


20B=6 
Assign the value 6 to numeric variable B. 


30C=A*B+3 


Assign the numeric variable C, the value resulting from 5 times 6 
plus 3. 


40 D$ = “HELLO” 
Assign the string “HELLO” to string variable D$. 


LIST 
List the BASIC program currently in memory 
LIST(line| first-|first-last -last] 


The LIST command displays a BASIC program listing that has 
been typed or LOADed into the Commodore 128’s memory so 
you can read and edit it. When LIST is used alone (without 
numbers following it), the Commodore 128 gives a complete 
LISTing of the program on the screen. The listing process may be 
slowed down by holding down the COMMODORE key, paused by 
CONTROL S or NO SCROLL KEY (and resumed by pressing any 
other key), or stopped by hitting the RUN/STOP key. If the word 
LIST is followed by a line number, the Commodore 128 shows 
only that line number. If LIST is typed with two numbers 
separated by a dash all lines from the first to the second line 
number are displayed. If LIST is typed followed by a number and 
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just a dash, the Commodore 128 shows all lines from that number 
to the end of the program. And if LIST is typed with a dash, then a 
number, all lines from the beginning of the program to that line 
number are LISTed. By using these variations, any portion of a 
program can be examined or brought to the screen for 
modification. In Commodore 128 mode, LIST can be used ina 
program. 


EXAMPLES: 
LIST 


Shows entire program. 


LIST 100- 
Shows from line 100 until the end of the program. 


LIST 10 
Shows only line 10. 


LIST -100 


Shows all line from the beginning to line 100 inclusive. 


LIST 10-200 
Shows lines from 10 to 200, inclusive. 


LOAD 


Load a program from a peripheral device such as the disk drive 
or Datassette 


LOAD[‘‘filename’’] [,device number] [,relocate flag] 


This is the command used to recall a program stored on disk or 
cassette tape. Here, the filename is a program name up to 16 
characters long, in quotes. The name must be followed by a 
comma (outside the quotes) and a number which acts as a 
device number to determine where the program is stored (disk or 
tape). If no number is supplied, the Commodore 128 assumes 
device number 1 (the Datassette tape recorder). 
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The relocate flag is a number (0 or 1) that determines where a 
program is loaded in memory. A relocate flag of 0 tells the 
Commodore 128 to load the program at the start of the BASIC 
program area. A flag of 1 tells the computer to LOAD from the 
point where it was SAVEd. The default value of the relocate flag is 
0. The relocate parameter of 1 is generally used when loading 
machine language programs. 


The device most commonly used with the LOAD command is the 
disk drive. This is device number 8, though the DLOAD command 
is more convenient to use when working with disk. 


If LOAD is typed with no arguments, followed by RETURN, the 
C128 assumes you are loading from tape and you are prompted 
to “PRESS PLAY ON TAPE”. When you press PLAY, the 
Commodore 128 starts looking for a program on tape. When the 
program is found, the Commodore 128 prints FOUND’ filename”, 
where the filename is the name of the first file which the 
datassette finds on the tape. Press the Commodore key to LOAD 
the found filename, or press the spacebar to keep searching on 
the tape. Once the program is LOADed, it can be RUN, LISTed or 
modified. 


NOTE: Pressing the spacebar does not cause the next file to be 
searched for in C64 mode. 


EXAMPLES: 
LOAD 
Reads in the next program from tape. 


LOAD “HELLO” 


Searches tape for a program called HELLO, and LOADs it if 
found. 


LOAD A$,8 


LOADs the program from disk whose name is stored in the 
variable A$. (This is equivalent to DLOAD(A$). 
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LOAD“HELLO”’,8 


Looks for the program called HELLO on disk drive number 8, 
drive 0. (This is equivalent to DLOAD “HELLO”) 


LOAD‘MACHLANG’’,8,1 


LOADs the machine language program called “MACHLANG” into 
the location from which it was SAVEd. 


The LOAD command can be used within a BASIC program to 
find and RUN the next program on a tape or disk. This is called 
chaining. 


LOCATE 
Position the bit map pixel cursor on the screen 
LOCATE x, y 


The LOCATE statement places the pixel cursor (PC) at any 
specified pixel coordinate on the screen. 


The pixel cursor (PC) is the coordinate on the bit map screen 
where drawing of circles, boxes, lines and points and where 
PAINTing begins. The PC ranges from X and Y coordinates 0,0 
through 319, 199 (scaled). Tne PC is not visible like the text 
Cursor but it can be controlled through the graphics statements 
(BOX, CIRCLE, DRAW etc.) The default location of the pixel 
Cursor is the coordinate specified as the X and Y portions in each 
particular graphics command. So the LOCATE command does 
not have to be specified. 


EXAMPLE: 


LOCATE 160,100 


Positions the PC in the centre of the bit map screen. Nothing will 
be seen until something is drawn. 


The PC can be found by using the RDOT(O) function to get the X- 
coordinate and RDOT(1) to get the Y-coordinate. The color 
source of the dot at the PC can be found by PRINTing RDOT(2). 
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MONITOR 
Enter the Commodore 128 machine language monitor 
MONITOR 


See Appendix J for details on the Commodore 128 Machine 
Language Monitor. 


MOVSPR 
Position or move sprite on the screen 


MOVSPR number,x1,y1 


Place the specified sprite at absolute coordinate x,y (scaled). 


MOVSPR number,+|- x, +|- y 


Move sprite relative to its Current position. 


MOVSPR number,X;Y 


Move sprite distance X at angle Y relative to its current position. 


MOVSPR number,x angle #y speed 

Move sprite at an angle relative to its original coordinates, in the 
clockwise direction and at the specified speed. 

where: 


number is sprite’s number (1 through 8) 
<,x1,y1> is coordinate of the sprite location (scaled) 


ANGLE is the angle (0-360) of motion in the clockwise direction 
relative to the sprites original coordinate. 


SPEED is a speed (0-15) at which the sprite moves. 


This statement locates a sprite at a specific location on the 
screen according to the SPRITE coordinate plane (not the bit 
map plane) or initiates sprite motion at a specified rate. See 
SPRMOV in Section 6 for a diagram of the sprite coordinate 
system. 
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EXAMPLES: 


MOVSPR 1,150,150 

Position sprite 1 near the centre of the screen, x,y coordinate 
150,160. 

MOVSPR 1,+20,-30 


Move sprite 1 to the right 20 coordinates and up 30 coordinates. 


MOVSPR 4, -50, +100 


Move sprite 4 to the left 50 coordinates and down 100 
coordinates. 


MOVSPR 5, 45 #15 


Move sprite 5 at a 45 degree angle in the clockwise direction, 
relative to its original x and y coordinate. The sprite moves at the 
fastest rate (15). 


NOTE: Once you specify an angle and a speed in the third form 
of the MOVSPR statement, you must set a speed of zero to stop 
the sprite moving. 


NEW 
Clear (erase) program and variable storage 
NEW 


This command erases the entire program in memory and clears 
any variables that may have been used. Unless the program was 
stored on disk or tape, it is lost. Be careful with the use of this 
command. The NEW command also can be used as a statement 
in a BASIC program. However, when the Commodore 128 gets to 
this line, the program is erased and everything stops. 


ON 


Conditionally branch to a specified program line number 
according to the results of the specified expression 


ON expression <GOTO|GOSUB> line #1 {, line #2,...] 
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This statement can make the GOTO and GOSUB statements 
operate like special versions of the (conditional) IF statement. 
The word ON is followed by an expression, then either of the 
keywords GOTO or GOSUB and a list of line numbers separated 
by commas. If the result of the expression is 1, the first line in the 
list is executed. If the result is 2, the second line number is 
executed and so on. If the result is 0, or larger than the number of 
line numbers in the list, the program resumes with the statement 
immediately following the ON statement. If the number is 
negative, an ILLEGAL QUANTITY ERROR results. 


EXAMPLE: 


10 INPUT X:IF X<0 THEN 10 
20 ON X GOSUB 30, 40, 50, 60 
25 GOTO 10 

30 PRINT “X = 1”:RETURN 

40 PRINT “X = 2”:RETURN 

50 PRINT ‘X = 3”:RETURN 

60 PRINT “X = 4”:RETURN 


When X=1, ON sends control to the first line number in the list 
(30). When X=2, ON sends control to the second line (40),etc. 


OPEN 
Open files for input or output 


OPEN logical file number, device number [,secondary address] 
[<, “filename, filetype, mode’’ | ,cmd string>] 


The OPEN statement allows the Commodore 128 to access files 
within devices such as a disk drive, a Datassette cassette 
recorder, a printer or even the screen of the Commodore 128. 
The word OPEN is followed by a logical file number, which is the 
number to which all other BASIC input/output statements will 
refer, such as PRINT &(write), INPUT #(read), etc. This number is 
from 1 to 255. 


The second number, called the device number follows the logical 
file number. Device number 0 is the Commodore 128 keyboard; 1 
is the cassette recorder: 3 is the Commodore 128 screen, 4-7 are 
normally the printer(s); and 8-11 are reserved for disk drives. It is 
often a good idea to use the same file number as the device 
number because it makes it easy to remember which is which. 
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Following the device number may be a third parameter called the 
secondary address. In the case of the cassette, this can be 0 for 
read, 1 for write and 2 for write with END-OF-TAPE marker at the 
end. In the case of the disk, the number refers to the channel 
number. See your disk drive manual for more information on 
Channels and channel numbers. For the printer, the secondary 
addresses are used to select certain programming functions. 


There may also be a filename specified for disk or tape OR a 
String following the secondary address, which could be a 
command to the disk/tape drive or the name of the file on tape or 
disk. If the filename is specified, the type and mode refer to disk 
files only. File types are PROGRAM, SEQUENTIAL, RELATIVE 
and USER; modes are READ and WRITE. 


EXAMPLES: 


10 OPEN 3,3 
OPENs the screen as file number 3 


20 OPEN 1,0 
OPENs the keyboard as file number 1 


30 OPEN 1,1,0,“DOT” 


OPENSs the cassette for reading, as file number 1, using “DOT” 
as the filename 


OPEN 4,4 
OPENSs the printer as file number 4 


OPEN 15,8,15 

OPENSs the command channel on the disk as file 15, with 
secondary address 15. (Secondary address 15 is reserved for the 
disk drive error command channel.) 

5 OPEN 8,8,12,‘‘TESTFILE,SEQ,WRITE”’ 


OPENs a sequential disk file for writing called TESTFILE as file 
number 8, with secondary address 12. 
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See also: CLOSE, CMD, GET#, INPUT#, and PRINT# statements 
and system variables ST, DS, and DS$. 


PAINT 
Fill area with color 
PAINT [color source],X,Y[,mode] 


where: 
color source 0 Bit map foreground 
1 Bit map background (default) 
2 Multicolor 1 
3 Multicolor 2 
X,Y starting coordinate, scaled (default at 
pixel cursor (PC)) 
mode O = paint an area defined by the color 


source selected (default) 
1 = paint an area defined by any non- 
background source 


The PAINT command fills an area with color, the area is defined 
by a fully enclosed shape around, but not including, the X,Y 
coordinate specified. Points where the color source is the same 
as the source of the pixel cursor are not PAINTed. (See example 
3.) 


If mode = 0 the area to be filled must be bounded by the color 
source, any other color sources which lie within this boundary are 
overPAINTed. (See example 1.) 


If mode = 1 the boundary of the area is any color source (except 


0). No color sources will be overPAINTed; I.e. only non-PAINTed 
areas can be filled when mode = 1. (See example 2.) 
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EXAMPLE 1: 


10 COLOR 0,1:COLOR 1,2:COLOR 2,5:COLOR 3,7 

20 GRAPHIC 3,1 multicolor graphics 

30 CIRCLE 1,80,100,30 draw circle in color source 1 

40 CIRCLE 3,80,100,35 draw circle in color source 3 

50 BOX 2,80,100,90,110,45,1 draw filled box in color source 2 
60 PAINT 3,70,100,0 paint inner circle in color source 3 bounded 
only by color source 3 


EXAMPLE 2: 
As example 1 but change line 60 to: 


60 PAINT 3,70,100,1 paint inner circle bounded by non- 
background color source 


EXAMPLE 3: 
As example 2 but add lines 70 and 80: 


70 COLOR 2,8 change color source to yellow 
80 PAINT 2,90,110,1 Attempt to repaint the box fails because 
color source in PAINT and at (90,110) are the same (2). 


PLAY 
Defines and plays musical notes and elements 


PLAY “‘[Vn] [On] [Tn] [Un] [Xn] [elements] [...]’’ 
where: 


Vn = Voice (n=1-3) 
On = Octave (n=0-6) 
Tn = Tune Envelope (n=0-9) 
0 = piano 
1 = accordion 
2 = Calliope Default envelope 
3 = drum Settings (See 
4 = flute ENVELOPE command) 


5 = guitar 

6 = harpsichord 
7 = organ 

8 = trumpet 

9 = xylophone 
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Un = Volume (n=0-9) (O=off; 9=full vol (VOL 15)) 

Xn = Filter on (n=1), off (n=0) 

Elements: 

NOTES: A,B,C,D,E,F,G 

Sharp* 

Flat* 

Whole note 

Half note 

Quarter note 

Eighth note 

sixteenth note 
Dotted* 

Rest 

Wait for all voices currently 
playing to end current 
measure 


2D O-OITS*H 


The PLAY statement gives you the power to select voice, octave 
and tune envelope (including ten predefined musical instrument 
envelopes), the volume and the notes you want to PLAY. All 
these controls are enclosed in quotes. 


All elements except R and M precede the musical notes in a 
PLAY string. 


NOTE: * These must precede each note. 
EXAMPLES: 


PLAY “V104TOUSXOCDEFGAB” 


Play the notes C,D,E,F,G,A and B in voice 1, octave 4, tune 
envelope 0 (piano - assuming that you have not altered it with 
ENVELOPE), at volume 5, with the filter off. 


PLAY “V305T6U7X1#B$AW.CHDQEIF” 


Play the notes B-sharp, A-flat, a whole dotted-C note, a half D- 
note, a quarter E-note and an eighth F-note. 

NOTE: You will need to set up a filter before you can hear 
anything with this example - try FILTER 1024,1). 
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POKE 
Change the contents of a RAM memory location 
POKE address, value 


The POKE statement allows changing of any value in the 
Commodore 128 RAM, and allows modification of many of the 
Commodore 128 Input/Output registers. Tne keyword POKE is 
always followed by two parameters. The first is a location inside 
the Commodore 128 memory, this can be a value from 0 to 
65535. The second parameter is a value from 0 to 255, which is 
placed in the location, replacing any value that was there 
previously. The value of the memory location determines the bit 
pattern of the memory location. In C128 mode the POKE occurs 
into the currently selected RAM bank. The POKE address 
depends on the BANK number. See BANK in this Encyclopaedia 
for the appropriate BANK configurations. 


EXAMPLE: 


10 POKE 53280,1 
Changes VIC border color (BANK 15 in C128 mode) 


NOTE: PEEK, a function related to POKE, which returns the 
contents of the specified memory location, is listed under 
FUNCTIONS. 


PRINT 
Output to the text screen 


The PRINT statement is the major output statement in BASIC. 
While the PRINT statement is the first BASIC statement most 
people learn to use, there are many variations of this statement. 
The word PRINT can be followed by any of the following: 


Characters inside of quotes (‘‘text’’ lines) 
Variable names (A, B, A$, X$) 

Functions (SIN(23), ABS(33)) 
Punctuation marks (; ,) 
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The characters inside quotes are often called literals because 
they are printed literally, exactly as they appear. Variable names 
have the value they contain (either a number or a string) printed. 
Functions also have their number values printed. 


Punctuation marks are used to help format the data neatly on the 
screen. The comma tabs to the nearest tenth column, while the 
semicolon prints items next to each other. (See also Section 3, 
Printing Numbers.) Either punctuation mark can be used as the 
last symbol in the statement. This results in the next PRINT 
Statement acting as if it is continuing the previous PRINT 
statement. Print on its own moves to the start of the next line - 
leaving a blank line. 


EXAMPLES: RESULTS 

10 PRINT “HELLO” HELLO 

20 A$="‘ THERE”’:PRINT “HELLO”’;A$ HELLO THERE 
30 A=4:B=2:PRINT A+B 6 

40 J=41:PRINT J;:PRINT J-1 41 40 


50 PRINT A;B;:D=A+B:PRINT D;A-B oe 
See also POS, SPC and TAB FUNCTIONS 


PRINT# 
Output data to files 
PRINT# file number, print list 


There are a few differences between this statement and the 
PRINT. Most importantly, the word PRINT# is followed by a 
number, which refers to the data file previously OPENed. The 
number is followed by a comma and a list of items to be output to 
the file. The semicolon acts in the same manner for spacing with 
printers as it does in the PRINT statement, commas output 10 
spaces. Some devices may not work with TAB and SPC. 


EXAMPLE: 


10 OPEN 4,4 
20 PRINT#4,““HELLO THERE!’’,A$,B$ 
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Outputs the data “HELLO THERE” and the variables A$ and BS 
to the printer. 


10 OPEN 2,8,2“DATAFILE,S,W”’ 
20 PRINT#2,A,B$,C,D 


This example outputs the data variables A, B$, C and D to the 
disk file number 2. 


NOTE: The PRINT# command is used by itself to clear the 
Channel to a device after outputting via CMD and before closing 
the file as follows: 


OPEN 4,4 
CMD4 
LIST 
PRINT#4 
CLOSE4 


See also CMD command. 


PRINT USING 
Output using format 


PRINT[#filenumber,] USING “format list’’; print list 


This statement defines the format of string and numeric items for 
printing to the text screen, printer or other device. The format is 
put in quotes. This is the format list. Then add a semicolon and a 
list of what is to be printed in the format for the print list. The list 
can be variables or the actual values to be printed, separated by 
commas. 


FORMAT STRING USED WITH 


CHARACTER NUMERIC STRING 
Hash sign (#) X x 

Plus sign (+) x 

Minus sign (-) X 

Decimal Point (.) X 

Comma (,) X 
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Dollar Sign ($) X 


Four Carets (“***) x 
Equal Sign (=) X 
Greater Than Sign (>) X 


The hash sign (#) reserves room for a single character in the 
output field. With Numeric Data if the data item contains more 
Characters than there are # signs in the format field, the entire 
field Is filled with asterisks (*); no characters are printed. 
EXAMPLE: 

10 PRINT USING “####”;X 


For these values of X, this format displays: 


X = 12.34 Ve 

X = 567.89 568 Note that the number is 
rounded up. 

X = 123456 Aas 


For a STRING Item, the string data is truncated at the bounds of 
the field. Only as many characters are printed as there are hash 
signs (#) in the format item. Truncation occurs on the right. 


The plus (+) and minus (-) signs can be used in either the first or 
last position of a format field, but not both. The plus sign is printed 
if the number is positive. The minus sign is printed if the number 
is negative. 


If a minus sign is used and the number is positive, a blank is 
printed in the character position indicated by the minus sign. 


If neither a plus nor a minus sign is used in the format field for a 
numeric data item, a minus sign is printed before the first digit or 
dollar symbol if the number is negative. No sign Is printed if the 
number is positive. This means that one additional character, the 
minus sign, is printed if the number is negative. If there are too 
many characters to fit into the field specified by the hash sign 
and plus/minus signs, then an overflow occurs and the field is 
filled with asterisks (*). 


kf=OF 


A decimal point (.) symbol designates the position of the decimal 
point in the number. There can be only one decimal point in any 
format field. If a decimal point is not specified in the format field, 
the value is rounded to the nearest integer and printed without 
decimal places. 


When a decimal point is specified, the number of digits preceding 
the decimal point (including the minus sign, if the value is 
negative) must not exceed the number of hash signs before the 
decimal point. If there are too many digits, an overflow occurs 
and the field is filled with asterisks (*). 


A comma (,) allows placing of commas in numeric fields. The 
position of the comma in the format list indicates where the 
commas appear in a printed number. Only commas within a 
number are printed. Unused commas to the left of the first digit 
appear as filler character. At least one hash sign must precede 
the first comma in a field. 


If commas are specified in a field and the number is negative, 
then a minus sign is printed as the first character, even if the 
Character position is specified as a comma. 


A dollar sign ($) symbol shows that a dollar sign will be printed in 
the number. If the dollar sign is to float (always be placed before 
the number), at least one hash sign must be specified before the 
dollar sign. If a dollar sign is specified without a leading hash 
sign, the dollar sign is printed in the position shown in the format 
field. If a plus or minus sign are specified in a format field with a 
dollar sign, the program prints the sign before the dollar sign. 
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EXAMPLES: 


FIELD EXPRESSION RESULT COMMENT 

## # -.1 -0.1 Leading zero added 

## # 1 1.0 Trailing zero added 

HHHH -100.5 -101 Rounded to no 
decimal places 

HHH -1000 wees Overflow because 


four digits and 
a minus sign cannot 


fit in field 
HHH. 10 10: Decimal point added 
HS## 1 $1 Leading dollar sign 


The up arrows or caret symbols (“***) are used to specify that 
the number is to be printed in E format (scientific notation). A 
hash sign must be used in addition to the four carets to specify 
the field width. The carets must appear after the hash sign in the 
format field. Four carets must be specified wnen a number is to 
be printed in E format. lf fewer than four carets are specified, a 
syntax error results. If more than four carets are specified, only 
the first four are used. The fifth and subsequent carets are 
interpreted as text symbols. You can specify a + or - sign after 
the carets if you require a trailing sign. An equal sign (=) is used 
to centre a string in a field. The field width is specified by the 
number of characters (hash sign and an equal sign) in the format 
field. If the string contains fewer characters than the field width, 
the string is centered in the field. If the string contains more 
Characters that can be fitted into the field, then the right-most 
characters are truncated and the string fills the entire field. A 
greater than sign (>) is used to right justify a string in a field. 
Other characters can be included in a format string, these are 
treated as literals. This allows you to build up tables and charts. 
see line 30 in the program below for a specific examples of this. 


EXAMPLE: 


5 X=32: Y=100.23: A$="‘CAT”: B$=“‘COMPUTER”’ 

6 F$=""* H=HHHHHHHHHH * HSHH.AH *”+CHR$(13) * 
10 PRINT USING “$##.##”;13.25,X,Y 

20 PRINT USING “###>#”;’”CBM”,A$ 

30 PRINT USING F$;A$,X,B$,Y 


CHR$(13) IS RETURN 
1¢7 99 


When this is RUN, line 10 prints: 


$13.25 $32.00 $***** Five asterisks (*****) are printed 
instead of a Y value because Y has five 
digits which does not conform to format 
list (as explained above). 


Line 20 prints this: 
CBM CAT 


Leaves two spaces before printing the string as defined in format 
list 


Line 30 prints this: 


* CAT * $23.00 * 
* COMPUTER * $100.23 * 


PUDEF 
Redefine symbols in PRINT USING statements 
PUDEF “nnnn” 


Where “nnnn” is any combination of characters, up to four in all, 
PUDEF allows you to redefine any of the following four symbols in 
the PRINT USING statement: blanks, commas, decimal points 
and dollar signs. These four symbols can be changed into some 
other character by placing the new character in the correct 
position in the PUDEF control string. 


Position 1 is the filler character. The default is a blank. Place a 


new character here for another character to appear in place of 
blanks. 


Position 2 is the comma character. Default is a comma. 
Position 3 is the decimal point. Default is a decimal point. 
Position 4 is the dollar sign. Default is a dollar sign. 


EXAMPLES: 
10 PUDEF “**” PRINTs * in the place of blanks. 
20 PUDEF “ <” PRINTs< in the place of commas. 
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NOTE: All positions up to the one(s) to be changed must be 
specified. 


For example PUDEF” = $” would print the $ in place of the dollar 
sign but the decimal point, comma and filler character would all 
be set to a space. 

PUDEF only affects numeric formats i.e. PUDEF"0” will change 
filler spaces in numbers to leading Os, but will not affect filler 
spaces in strings. 


The character to replace the $ has no effect unless the § is 
preceded by a # (i.e. is floating). 


READ 


Read data from DATA statements and input it into the 
computer's memory (while the program is RUNning) 


READ variable list 


This statement takes information from DATA statements and 
stores them in variables, where the data can be used by the 
RUNning program. The READ statement variable list may contain 
both strings and numbers. Be careful to avoid reading strings 
where the READ statement expects a number, this produces a 
TYPE MISMATCH ERROR message. 


The data in the DATA statements are READ in sequential order. 
Each READ statement can read one or more data items. Every 
variable in the READ statement requires a data item. If one is not 
supplied, an OUT OF DATA ERROR occurs. 


In a program, you can READ the data and then reREAD by 
issuing the RESTORE statement. The RESTORE sets the 
sequential data pointer back to the beginning, where the data can 
be READ again. See the RESTORE statement. 


EXAMPLES: 


10 READ A, B, C 
20 DATA 3, 4, 5 


READ 3 data items (which must be numeric or an error will 
occur) into variables A, B, and C. 
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10 READ AS, BS, C$ 
20 DATA JOHN, PAUL, GEORGE 


READ three strings from data statements. 


10 READ A, B$, C 
20 DATA 1200, NANCY, 345 


READ a numeric variable,a string variable and another numeric 
variable. 


RECORD 
Position relative file pointers 
RECORD# logical file number, record number [,byte] 


This statement positions a relative file pointer to select any byte 
(character) of any record in the relative file. The logical file 
number can be in the range between 1 and 255. The record 
number can be in the range 1 through 65535. Byte number is in 
the range 1 through 254. See your disk drive manual for details 
about relative files. 


When the record number value is set higher than the last record 
number in the file, the following occurs: 


For a write (PRINT #) operation, additional records are created to 
expand the file to the desired record number. 


For a read (INPUT #) operation, a null record is returned and a 
“RECORD NOT PRESENT ERROR” occurs. 


EXAMPLES: 


10 DOPEN #2,“CUSTOMER’”’ 
20 RECORD#2,10,1 

30 PRINT#2,A$ 

40 DCLOSE #2 


This example opens an existing relative file called “CUSTOMER” 
as file number 2 in line 10. Line 20 positions the relative file 
pointer at the first byte in record number 10. Line 30 actually 
writes the data, A$, to the file. 
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The RECORD command accepts variables for its parameters. It 
is often convenient to place a RECORD command within a 
FOR...NEXT or DO loop. Also see DOPEN. 


REM 
Comments or remarks about the operation of a program line 
REM [message] 


The REMark statement is a note to whoever is reading a listing of 
the program. REM may explain a section of the program, give 
information about the author, etc. REM statements do not affect 
the operation of the program, except to add length to it (and 
therefore use more memory). Nothing to the right of the Keyword 
REM is interpreted by the computer as an executable instruction. 
Therefore, no other executable statement can follow a REM on 
the same line. 


EXAMPLE: 
1010 NEXT X: REM END OF MAIN PROGRAM LOOP 


RENAME 
Change the name of a file on disk 


RENAME [Ddrive number, ]|‘‘old filename” TO ‘‘new filename” 
[<ON| ,>Udevice number] 


This command is used to rename a file on a disk, from the old 
filename to the new filename. The disk drive does not RENAME a 
file if itis OPEN. 


EXAMPLES: 


RENAME DO,“TEST” TO “FINAL TEST” 
Change the name of the file “TEST” to “FINAL TEST”. 


RENAME D0,(A$) to (B$),U9 


Change the filename specified in A$ to the filename specified in 
B$ on drive 0, device number 9. Remember, whenever a variable 
name is used as a filename, it must be enclosed in parentheses. 
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RENUMBER 
Renumber lines of a BASIC program 


RENUMBER [new starting line number] [,increment] 
[,old starting line number] 


The new starting line is the number of the first line in the program 
after renumbering; the default value is 10. The increment is the 
interval between line numbers, (i.e., 10, 20, 30, etc.); the 
increment default value is also 10. The old starting line number is 
the first line number before you renumber the program. This 
allows renumbering of a select portion of the program. The 
default in this case is the first line of the program. This command 
Can only be executed from direct mode. 


A “UNRESOLVED REFERENCE ERROR’ occurs if any reference 
to line number that does not exist is encountered. An “OUT OF 
MEMORY” occurs if RENUMBERing expands the program 
beyond its limits. A “LINE NUMBER TOO LARGE ERROR" 
occurs if RENUMBER generates a line number of 64000 or 
higher. These errors leave the program unharmed. 


EXAMPLES: 


RENUMBER 

Renumbers the program starting at 10, and increments each 
additional line by 10. 

RENUMBER 20, 20, 15 


Starting at line 15, renumbers the program. Line 15 becomes line 
20, and other lines are numbered in increments of 20. 


RENUMBER, , 65 


Starting at line 65, renumbers in increments of 10. Line 65 
becomes line 10. If you omit a parameter, you must still enter a 
comma as a placeholder. There must be no line between 10 and 
64 inclusive. 


ALWAYS SAVE YOUR PROGRAM BEFORE RENUMBERING, 


because very long programs can cause a SYSTEM crash when 
RENUMBERed with larger line numbers. 
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Also note that long programs should be RENUMBERed in FAST 
mode as they will take a long time to renumber (up to 30 minutes 
for a 55K program in FAST). 


If you only have a 40 column display use FAST:RENUMBER... 
<RETURN>. Then type SLOW <RETURN>. While 
RENUMBERing is taking place you will not see anything 
happening. When RENUMBERING has finished your display will 
return. 

lf you have an 80 column display or 40/80 column display select 
the 80 column screen before typing FAST. 


RESTORE/ RESTORE 


Reset READ pointer to DATA statement so the DATA can be 
reREAD 


RESTORE C64 mode 
RESTORE [line #] C128 mode 


When executed in a program, the pointer to the item ina DATA 
statement that is to be READ next is reset to the first item in the 
DATA statement. This provides the capability to reREAD the data. 
If a line number follows the RESTORE statement the READ 
pointer is set to the first data item after the specified program line. 
Otherwise the pointer is reset to the beginning of the BASIC 
program. In C64 mode there is no option to specify the line 
number, i.e. you can only RESTORE to the beginning of the 
program. 


EXAMPLES: 


10 FORI=1TO3 
20 READ X 

30 T=X+T 

40 NEXT 

45 PRINT T 

50 RESTORE 

69 GOTO 10 

70 DATA 10.20,30 
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This example READs the data in line 70 and stores it in numeric 
variable X. It adds the total (T) of all the numeric data items. Once 
all the data has been READ, three cycles through the loop, the 
READ pointer is RESTOREd to the beginning of the program and 
it returns to line 10 and performs repetitively. 


10 READ A,B,C 

20 DATA 100,500,750 
30 READ X,Y,Z 

40 DATA 36,24,38 

50 RESTORE 40 

60 READ S,P,Q 

70 PRINT A,B, C 

80 PRINT X,Y,Z 

90 PRINT S,P,Q 


This example RESTORES the DATA pointer to the first data item 
in line 40. When line 60 is executed, it will READ the DATA 
36,2438 from line 40, since you don't need to READ line 20's 
DATA again. 


NOTE: If a line a number is specified the line must exist! A 
variable can be used e.g. RESTORE LR. 


RESUME 


Define where the program will continue (RESUME) after an error 
has been trapped 


RESUME [line #| NEXT] 


This statement is used to restart program execution after 
TRAPping an error. With no parameters, RESUME attempts to re- 
execute the line in which the error occurred. RESUME NEXT 
resumes execution at the statement immediately following the 
one containing the error; RESUME followed by a line number will 
GOTO the specific line and resume execution from that line 
number. RESUME can only be used in program mode. 
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EXAMPLE: 


10 TRAP 100 

20 INPUT “ ENTER A NUMBER’’,A 

30 B=100/A 

40 PRINT“THE RESULT=”’,B:PRINT’ THE END” 

50 PRINT“DO YOU WANT TO RUN IT 
AGAIN(Y/N)”:GETKEYZ$:IF Z$=“Y” THEN 20 

60 STOP 

100 INPUT“ENTER ANOTHER NUMBER (NOT ZERO)”;A 

110 RESUME 


This example traps a “division by zero error” in line 30 if 0 is 
entered in line 20. If zero is entered, the program goes to line 100, 
where you are asked to input another number besides 0. Line 110 
returns to line 30 to complete the calculation. Line 50 asks if you 
want to repeat the program again. If you do, press the Y key. 


RETURN 
Return from subroutine 
RETURN 


This statement is always paired with the GOSUB statement. 
When the program encounters a RETURN statement, it goes to 
the statement immediately following the last GOSUB command 
executed. If no GOSUB was previously issued, then a RETURN 
WITHOUT GOSUB ERROR message is displayed and the 
program stops. All subroutines end with a RETURN statement 


EXAMPLE 


10 PRINT “ENTER SUBROUTINE” 
20 GOSUB 100 
30 PRINT “END OF SUBROUTINE” 


90 STOP 
100 PRINT “SUBROUTINE 1” 
110 RETURN 


This example calls the subroutine at line 100 which prints the 
message “SUBROUTINE 1” and RETURNs to line 30, the rest of 
the program. 
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RUN/RUN 
Execute BASIC program 


RUN [line #} 
RUN “filename” [,Ddrive number] [,Udevice number] 
C128 mode only 


Once a program has been typed into memory or LOADed, the 
RUN command executes it. RUN clears all variables in the 
program before starting program execution. If there is a number 
following the RUN command, execution starts at that line number. 
If there is a filename following the RUN command, the named file 
is loaded from the disk drive and RUN, with no further action 
required of the user. RUN may be used within a program. The 
default drive number is 0 and default device number is 8. 


EXAMPLES: 


RUN 


Starts execution from the beginning of the program currently in 
memory. 


RUN 100 


Starts program execution at line 100 


RUN‘PRG1” 
DLOADS “PRG1” from disk drive 8, and runs it from the first line. 


RUN(A$) 


DLOADs the program named in the variable A$ and 
runs it from the first line. 


SAVE 
Store the program in memory to disk or tape 
SAVE [‘‘filename’’] [,device number] [,EOT flag] 


This command stores the program Currently in memory onto 
Cassette tape or disk for later retrieval. If SAVE is typed alone an 
unnamed file will be saved to tape. Tape is a sequential system 
and, therefore,it is up to the user to ensure that there is nothing 
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important on the tape before SAVEing (see VERIFY). To give your 
program a name simply enciose the chosen name in quotes (or 
use a string variable) immediately after typing SAVE. A filename 
can be up to 16 characters. 


NOTE: When SAVEing to disk you must specify a filename or you 
will get a MISSING FILE NAME ERROR. 


To specify the device number (e.g. 1 for tape) place a comma 
followed by the device number after the closing quote following 
the filename. 


The final parameter (EOT) follows the device number and is 
again separated by a comma. It has no significance when used 
with disk and can have one of four values when used with tape. 
These options are: 


0 Default - no action 


1 SAVE so that the relocate function of LOAD does not work, 
i.e. the file will always load back at the address from which it 
was SAVEd. 


2 Write an END OF TAPE marker at the end of the file — 
attempts to LOAD beyond the end of a file saved in this way 
will generate a FILE NOT FOUND ERROR. 


3. SAVEs in non-relocatable format (1) and writes the EOT (2) 


NOTE: |f you specify the device number or EOT parameter 
the filename (and device number) must be included. For 
tape this may be a null ("’). See the following examples. 


EXAMPLES: 


SAVE ‘‘HELLO”’ 
Stores a program on tape, under the name HELLO. 


SAVE A$,8 
Stores on disk, with the name stored in variable A$. 


SAVE “HELLO”, 8 


Stores on disk, with name HELLO (equivalent to DSAVE 
“HELLO”). 
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SAVE “HELLO”, 1, 2 


Stores on tape, with name HELLO, and places an END-OF TAPE 
marker after the program. 


SAVE *°’’,1,3 


Stores on tape, with no name, places an EOT marker after the 
program, does not allow the program to be relocated on loading. 


SCALE 

Alter scaling in graphics mode 
SCALE n [,xmax,ymax] 
where: 

n= 1 (on) or O (off) 


xmax Is in the range 320-32767 default 1023 (hi-res) 2047 
(multicolor) 
ymax is in the range 200-32767 default 1023 


Changes the scaling of the bit map display coordinates in both 
multicolor and high resolution modes. Coordinates for the 
MOVSPR command are also scaled. Maps many logical points to 
one physical point. 


This is helpful when you need to plot data over a wide range of 
values - it will not help if you have a large cluster of data with only 
high values. 


Because multicolor uses 2 physical pixels on the x-axis per dot, 
its normal display is 

X=0to 159;Y=0to 199 
as opposed to 

X=0to 319; Y=0to 199 


If you wish to use the same coordinates for multicolor and hi-res 
use SCALE 1,640,200 after setting up a multicolor screen and 
use the default SCALE values for both types of screen. 

NOTE: The GRAPHICS command turns scaling off i.e. is 
equivalent to GRAPHIC...: SCALE 0. 
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EXAMPLE: 


10 GRAPHIC 1 :GOSUB 100 

20 SCALE 1 :GOSUB100 

30 SCALE 1,5000,5000 :GOSUB100 
40 END 

100 CIRCLE 1,160,100,60:RETURN 


SCNCLR 

Clear screen 
SCNCLR[mode number] 
The modes are as follows: 


Mode Number Mode 

40 column (VIC) text 
bit map* 

split screen bit map* 
multicolor bit map* 
split screen multicolor 
bit map* 

5 80 column (8563) text 


This statement with no argument clears the graphic screen, if it is 
present otherwise the current text screen is cleared.* * 


fWON-O 


EXAMPLES: 

SCNCLR 5 Clears 80 column text screen 

SCNCLR 1 Clears the (VIC) bit map screen 

SCNCLR 4 Clears the (VIC) multicolor bit map split screen 


NOTE: * The bit map area is the same for both hi-res and 
multicolor, the different mode numbers select other parameters to 
Clear e.g. 40 column text (2 and 4) color ram (3 and 4). 


** If a graphics screen has been created but is not selected 
(GRAPHICS =0) it will not be cleared. If you are using 2 screens 
(80 columns for text and 40 columns for graphics) SCNCLR will 
clear both text and graphics screens if called from the 80 column 
screen. 
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SCRATCH 
Delete a file from the disk directory 


SCRATCH “filename” [,Ddrive number] [<ON | ,>Udevice 
number] 


This command deletes a file from the disk directory. As a 
precaution, the system asks “Are you sure,” (in direct mode only) 
before the Commodore 128 starts the operation. Type a Y to 
perform the SCRATCH or press any other key to cancel the 
operation. Use this command to erase unwanted files, and to 
Create more space on the disk. The filename may contain 
template, or wildcards (?,*). The default drive number is 0 and 
default device number is 8. 


EXAMPLE: 
SCRATCH “MY BACK”, DO 
This erases the file MY BACK from the disk in drive O of unit 8. 


SLEEP 

Delay program for a specific period of time 
SLEEP N 

where N is seconds 0< n < 65535 


If you select a delay which is too long for your program and you 
want to halt it, the STOP key can be used to break into a delay. 


SLOW 
Return the Commodore 128 to 1Mhz operation 
SLOW 


The Commodore 128 is capable of running the 8502 
microprocessor at a speed of 1 or 2 megahertz (Mhz). 


The SLOW command slows down the microprocessor to 1 
Megahertz from 2 Megahertz. The FAST command sets the 
Commodore at 2 Mhz. The Commodore 128 can process 
commands substantially faster operating at 2 Mhz than at 1 Mhz. 
Note, however, that the 40 column screen cannot be used at 
2Mhz. 
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SOUND 
Outputs sound effects and musical notes 
SOUND v,f,d[,dir] [,m] [,s] [,w] [,p] 


where: v= voice (1..3) 
= frequency value (0..65535) 
= duration (0.32767 


dir = step direction (O(up) ,1(down) or 2(oscillate)) 
default=0 

m = minimum frequency (if sweep is used) 
(0.65535) default=0 

s= step value for sweep (0..65535) default=0 

w= waveform (0=triangle,!=sawtooth,2=pulse, 
3=noise) default=2 

p= pulse width (0..4095) default=2048 


The SOUND command is a fast and easy way to create sound 
effects and musical tones. The three required parameters v, f and 
d select the voice, frequency and duration of the sound. The 
duration is in units called jiffies. Sixty jiffies equals 1 second. 


The SOUND command can sweep through a series of 
frequencies which allows sound effects to pass through a range 
of notes. Specify the direction of the sweep with the DIR 
parameter. Set the minimum frequency of the sweep with M and 
the step value of the sweep with S. Select the appropriate 
waveform with W and specify P as the width of the variable pulse 
waveform if selected in W. 


EXAMPLES: 


SOUND 1,40960,60 
Play a SOUND at frequency 40960 in voice 1 for 1 second. 


SOUND 2,2000,5,0,2000,100 


Output a sound by sweeping through frequencies starting at 2000 
and incrementing upward in units of 100. 


SOUND 3,5000,1,2,3000,500,1 
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This example outputs a range of sounds starting at a minimum 
frequency of 3000, through 5000, in increments of 500. The 
direction of the sweep is back and forth (oscillating). The 
selected waveform is Sawtooth and the voice selected is 3. 


SPRCOLOR 
Set multicolor 1 and/or multicolor 2 colors for all sprites 


SPRCOLOR [smer-1] [,smcr-2] 
where: 


smcr-1 multicolor 1 for all sprites, 
smcr-2 multicolor 2 for all sprites. 


These parameters may be any color from 1 through 16 
EXAMPLES: 


SPRCOLOR 3,7 


sets sprite multicolor 1 to red and multicolor 2 to blue. 


SPRCOLOR 1,2 


Sets sprite multicolor 1 to black and multicolor 2 to white. 


SPRDEF 
Enter the SPRite DEFinition mode to create and edit sprite images 
(40 column display only). 


SPRDEF 


The SPRDEF command defines sprites interactively. 


Entering the SPRDEF command, displays a sprite work area on 
the screen which is 24 characters wide by 21 characters tall. 
Each character position in the grid corresponds to a sprite pixel 
in the sprite displayed to the right of the work area. Here is a 
summary of the SPRite DEFinition mode operations and the keys 
that perform them: 
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user input description 


RETURN key Exits sprite designer mode at the 
SPRITE NUMBER? prompt only. 
1-8 Selects a sprite number. A Turns on 


and off Automatic cursor movement. 


CRSR keys Moves cursor. 
RETURN key Moves cursor to start of next line. 
HOME key Moves cursor to top left corner of 
sprite work area. 
CLR key Erases entire grid. 
1-4 Selects color source. 
1 clear 


2 foreground 
3 multicolor 1 
4 multicolor 2 


<CTRL> 1-8 Selects sprite foreground color (1-8). 

Commodore key(1-8) Selects sprite foreground color (9-16). 

STOP key Cancels changes and returns to 
prompt. 

SHIFT RETURN Saves sprite in memory and returns to 
SPRITE NUMBER? prompt. 

X Expands sprite in X (horizontal) 


direction - Toggle. 

Y Expands sprite in Y (vertical) direction 
- Toggle. 

M Multicolor sprite — Toggle 

C Copies sprite data from one sprite to 
another. 


NOTE: Using SPRDEF will clear the bit map screen. 


SPRITE 


Turn on or off, color, expand and set screen 
priorities for a sprite 


SPRITE <number> [,0n/off] [,fgnd] [, priority] [,x-exp] 
L,y-exp] [,;mode] 


The SPRITE statement controls most of the characteristics of a 
sprite. 


i Were: 


Parameter Description 


number Sprite number (1-8). 

on/off Turn sprite on (1) or off (0). 

fgnd Sprite foreground color (1-16). 
priority Priority is 0 if sprites appear in front of 


objects on the screen priority is 1 if sprites 
appear behind objects on the screen. 


x-exp Horizontal EXPansion on (1) or off (0). 
y-exp Vertical EXPansion on (1) or off (0). 
mode Select standard sprite (QO) or multicolor 


sprite (1). (See SPRCOLOR) 


Unspecified parameters in subsequent sprite statements take on 
the characters of the previous SPRITE statement. You may check 
the characteristics of a SPRITE with the RSPRITE function. 


EXAMPLES: 


SPRITE 1,1,3 


Turn on sprite number 1 and color it red. 


SPRITE 2,1,7,1,1,1 


Turn on sprite number 2, color it blue make it pass behind objects 
on the screen and expand it in the vertical and horizontal 
directions. 


SPRITE 6,1,1,0,0,1,1 


Turn on SPRITE number 6, color it black. The first O tells the 
computer to display the sprites in front of objects on the screen. 
The second 0 and the 1 following tell the C128 to expand the 
sprite vertically only. The last 1 specifies the sprite to be 
displayed in multicolor mode. Use the SPRCOLOR command to 
select the sprite’s multicolor. 


SPRITE 7,,,,1 


Set the horizontal expansion of sprite number 7 - all other options 
retain their previous settings. 
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SPRSAV 


Store sprite data from a text string variable into a sprite storage 
area or vice versa 


SPRSAV origin,destination 


This command transfers a sprite image from a string variable to a 
sprite storage area. It can also transfer the data from the sprite 
storage area into a string variable. Either the origin or the 
destination can be a sprite number or a string variable but they 
both cannot be string variables. If you are moving a string into a 
sprite, only the first 63 bytes of data are used. The rest are 
ignored since a sprite can only hold 63 data bytes. 


EXAMPLES: 


SPRSAV 1,A$ 
Transfers the image pattern from sprite 1 to the string named A$. 


SPRSAV B$,2 
Transfers the data from string variable B$ into sprite 2. 


SPRSAV 2,3 
Transfers the data from sprite 2 to sprite 3. 
NOTE: SPRSAV sprite, string produces a string in the same 


format as SSHAPE so that it can be used with GSHAPE to ‘fix’ a 
sprite onto a hi-res screen. The string will be 67 characters long. 


SSHAPE/GSHAPE 
Save/retrieve shapes to/from string variables 


SSHAPE and GSHAPE are used to save and load rectangular 
areas of multicolor or bit mapped screens to/from BASIC string 
variables. The command to save an area of the screen into a 
string variable is: 


SSHAPE string variable, X1, Y¥1 [,X2,¥2] 


ews 


where: 


string variable String name to save data in 

X1,Y1 Corner coordinate (0,0 through 320,200) 
(scaled) 

X2,Y2 Corner coordinate opposite (X1,Y1) 


(default is the PC) 


Because BASIC limits strings to 255 characters, the size of the 
area that can be saved is limited. The string size required can be 
calculated using one of the following (unscaled) formulas: 


L(h-r) = INT ( (ABS(x1-x2) + 1) / 8 + 99) * (ABS(y1-y2)+1)+4 
L(mem)= INT ((ABS(x1 -x2) +1) / 4+ .99) * (ABS(y1-y2) +1) + 4 


NOTE: Provided x2-x1 is 23 and the graphic mode is hi-res 
(mode 1 or 2) a string produced by SSHAPE can be used to 
generate a Sprite (see SPRSAV). 


The command to retrieve (load) the data from a string variable 
and display it on specified screen coordinates is: 


GSHAPE string variable,[X,Y] [,mode] 


where: 
string Contains shape to be drawn 
X,Y Top left coordinate (0,0 through 319,199) 
telling where to draw the shape (scaled- 
the default is the pixel cursor) 
mode Replacement mode: 


0: place shape as is (default) 
1: invert (reverse) shape 

2: OR shape with area 

3: AND shape with area 

4: XOR shape with area 


The replacement mode allows you to change the data in the 
string variable so you can invert it, perform a logical OR exclusive 
OR or AND operation, on the image. 


Also see the LOCATE command for information on the pixel 
Cursor. 
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EXAMPLES: 


SSHAPE A$,10,10 

Saves a rectangular area from the coordinates 10,10 to the 
location of the pixel cursor, into string variable A$. 

SSHAPE B$,20,30,47,51 

Saves a rectangular area from top left coordinate (20,30) through 
bottom right coordinate (47,51) into string variable B$. 

GSHAPE A$,120,20 

Retrieves shape continued in string variable A$ and displays it at 
top left corner at coordinate (120,20). 

GSHAPE B$,30,30,1 


Retrieves shape contained in string variable B$ and displays it at 
top left coordinate (30,30). The shape is inverted due to the 
replacement mode being selected by the 1. 


NOTE: Beware using modes 1-4 with multicolor shapes. You may 
obtain unpredictable results. 


STASH 
Move contents of host memory to expansion ram 


STASH #bytes, intsa, expsa, expb 
Refer to FETCH command for description of parameters. 


STOP 
Halt program execution 
STOP 


This statement halts the program. A message, BREAK IN LINE 
XXX occurs (in program mode), where XXX is the line number 
containing the STOP command. The program can be restarted at 
the statement following STOP if the CONT command is used 
immediately, without any editing occurring in the listing. The 
STOP statement is often used while debugging a program. 
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SWAP 
Swap contents of host RAM with contents of expansion RAM. 
SWAP #byftes, intsa, expsa, expb 


Refer to FETCH command for description of parameters. 


SYS/SYS 


Called and execute a machine language subroutine at 
the specified address 


SYS address C64 mode 
SYS address [,a] [,x] [,y] [,s] C128 mode 


This statement performs a call to a machine code subroutine at 
the given address in a memory configuration set up according to 
the BANK command. Optionally, arguments a,x,y and s are 
loaded into the accumulator, x, y and status registers, 
respectively before the subroutine is called. 


The address range is 0 to 65535. The program begins executing 
the machine-language program starting at that memory location. 
Also see the BANK command. 


EXAMPLES: 


SYS 40960 


Calls and executes the machine-language routine at location 
40960. 


SYS 8192,0 


Calls and executes the machine-language routine at location 
8192 and loads zero into the accumulator. 


TEMPO 
Define the speed of the song being played 
TEMPO n 


where n is a relative duration between (1 and 255) 
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The actual duration for a whole note is determined by using the 
formula given below: 


whole note duration = 23.06/n seconds 


The default value is 8, and note duration increases with n. 


EXAMPLES: 

TEMPO 16 Defines the Tempo at 16 

TEMPO 1 Defines the TEMPO at the slowest speed 
TEMPO 250 Defines the TEMPO at 250 


TRAP 


Detect and handle program errors while a BASIC program is 
RUNning 


TRAP [line #] 


When turned on, TRAP intercepts all error conditions (excluding 
DOS error messages but including the STOP KEY). In the event 
of any execution error, the error flag is set and execution is 
transferred to the line number specified in the TRAP statement. 
The line number in which the error occurred can be found by 
using the system variable EL. The specific error condition is 
contained in system variable ER. The string function ERR$ (ER) 
gives the error message corresponding to the error condition. 


The RESUME statement can be used to resume program 
execution. TRAP with no line number turns off error trapping. An 
error ina TRAP routine cannot be trapped. 

EXAMPLES: 


100 TRAP 1000 


If an error occurs, go to line 1000 


1000 ?7ERR$ (ER);EL 


Print the error message, and the error line number 


Tf 


1010 RESUME 
Resume program execution 


TROFF 
Turn off error TRACing mode 
TROFF 


This statement turns off trace mode. 


TRON 
Turn on error TRACing mode 
TRON 


TRON is used in program debugging. This statement begins trace 
mode. When you RUN the program, the line numbers of the 
program appear in brackets before any action for that line occurs. 


If you have multistatement lines, the line number will be printed 
before each statement is processed. 


VERIFY 


Verify program in memory against one on saved to disk 
or tape 


VERIFY “filename” [,device number] [,relocate flag] 


This command causes the Commodore 128 to check the 
program on tape or disk against the one in memory, to determine 
if the program is really SAVEd. This command is also very useful 
for positioning a tape so that the Commodore 128 writes after the 
last program on the tape. 


VERIFY, with no arguments after the command, causes the 
Commodore 128 to check the next program on tape, regardless 
of its name, against the program now in memory. VERIFY, 
followed by a program name in quotes or a string variable, 
searches the tape for that program and when found checks it 
against the program in memory. VERIFY, followed by a name, a 
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comma and a number, checks the program on the device with 
that number (1 for tape, 8 for disk). The relocate flag is the same 
as in the LOAD commana. It verifies the program from the 
memory location from which it was SAVEd. (See also DVERIFY.) 


EXAMPLES: 


VERIFY 
Checks the next program on the tape. 


VERIFY “HELLO” 
Searches for HELLO on tape, checks it against memory. 


VERIFY “HELLO”, 8,1 
Searches for HELLO on disk, then checks it against memory. 


VERIFY” lasttfile”’ 


Searches tape for lastfile checks it, reports an error if there is no 
match. You can then save your new program after it, without 
erasing previous programs. 


NOTE: If a graphic area is allocated or deallocated after a SAVE, 
VERIFY and DVERIFY will report an error. Technically this is 
correct. BASIC text in this case has been moved from its original 
(saved) location to another address range. Hence, VERIFY, which 
performs byte-to-byte comparisons, will fail, even though the 
program is valid. 


VOL 
Define output level of sound 
VOL volume level 


This statement sets the volume for SOUND and PLAY 
Statements. VOLUME level can be set from 0 to 15, where 15 is 
the maximum volume, and 0 is off. VOL affects all voices. 


EXAMPLES: 
VOL 0 Turns volume off. 
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VOL 1 Sets volume to its lowest level. 


VOL 15 Set volume for SOUND and PLAY statements to its 
highest level. 


WAIT 
Pause program execution until a data condition is satisfied 
WAIT Location, mask-1[,mask-2] 


The WAIT statement causes program execution to be suspended 
until a given memory address recognizes a specified bit pattern 
or value. In other words, WAIT can be used to halt the program 
until some external event has occurred. This is done by 
monitoring the status of bits in the Input/Output registers. The 
data items used with the WAIT can be any values. For most 
programmers, this statement should never be used. It causes the 
program to halt until a specific memory location's bits change in 
a specific way. This is used for certain |/O operations and almost 
nothing else. The WAIT statement takes the value in the memory 
location and performs a logical AND operation with the value in 
mask-1. If mask-2 is specified, the result of the first operation is 
exclusively ORed with mask-2. In other words, mask-1 “filters 
out” any bits not to be tested. Where the bit is 0 in mask-1, the 
corresponding bit in the result will always be 0. The mask-2 value 
flips any bits, so that an off condition can be tested for as well as 
an on condition. Any bits being tested for a O should have a 1 in 
the corresponding position in mask-2. If corresponding bits of the 
mask-1 and mask-2 operands differ, the exclusive-OR operation 
gives a bit result of 1. If the corresponding bits get the same 
result the bit is 0. It is possible to enter an infinite pause with the 
WAIT statement, in which case the RUN/STOP and RESTORE 
keys can be used to recover. WAIT may require a BANK 
command if the memory you wish to access is not in the 
currently selected BANK. 


The following examples are for C128 mode only. The first 
example WAITs until a key is pressed on the tape unit to continue 
with the program. The second example will WAIT until the SHIFT 
key is pressed and then released. The third example will WAIT 
until either bit 7 (128) is on or bit 4 (16) is off. 
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EXAMPLES: 


WAIT 1, 32, 32 
WAIT 211,1:WAIT211,1,1 
WAIT 36868, 144, 16 


(144 and 16 are binary masks. 144 = 10010000 in binary and 16 
= 10000 in binary.) 


WIDTH 
Set the width of drawn lines 
WIDTH n 


This command sets the width of lines drawn using BASIC’s 
graphic commands to either single or double width. Giving na 
value of 1 defines a single width line; a value of 2 defines a 
double width line. 


EXAMPLES: 
WIDTH 1 Set width for graphic commands 
WIDTH 2 Set double width for drawn lines 


WINDOW 
Defines a screen window 


WINDOW top left col,top left row,bot right col, 
bot right row(,clear] 


This command defines a logical window within the 40 or 80 
column text screen. The coordinates must be in the range 0- 
39/79 for column values and 0-24 for row values. The clear flag, 
if provided (1), causes a screen-clear to be performed (but only 
within the limits of the newly described window). 


EXAMPLES: 


WINDOW 5,5,35,20 


Define a window with top left corner coordinate (5,5) and bottom 
right corner coordinate (35,20). 
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WINDOW 10,2,33,24,1 


Define a window with upper left corner coordinate (10,2) and 
lower right corner coordinate (33,24). Also clears the portion of 
the screen within the window as specified by the 1. 


NOTE: If you specify a column greater than 39 on a 40 column 
display you will get an “ILLEGAL QUANTITY ERROR”. 
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SECTION 18 


Basic Functions 


BASIC FUNCTIONS 
The format of the function description is: 
FUNCTION (argument) 
where the argument can be a numeric value, variable or string. 
Each function description is followed by an EXAMPLE. The lines 


appearing in bold face in the examples are the functions you type 
in. The line without bold is the computer's response. 


ABS 
Return absolute value 
ABS (X) 


The absolute value function returns the positive value of the 
argument. 


EXAMPLE: 
PRINT ABS (7*(-5)) 
35 
ASC 
Return CBM ASCII code for character 
ASC(X$) 


This function returns the ASCII code of the first character of X$. 
In C128 Mode you no longer have to append CHR§$(0) to a null 
String. ILLEGAL QUANTITY ERROR is no longer issued. 


EXAMPLE: 


X$="C128”:PRINTASC(X$) 
67 


ATN 
Return angle whose tangent is X radians 
ATN (X) 


This function returns the angle whose tangent is X, measured in 
radians. 


EXAMPLE: 
PRINT ATN (3) 
1.24904577 


BUMP 
Return sprite collision information 
BUMP (N) 


To determine which sprites have collided since the last check, 
use the BUMP function. BUMP(1) records which sprites have 
collided with each other and BUMP(2) records which sprites have 
collided with other objects on the screen. COLLISION need not 
be active to use BUMP. The bit positions (0-7) in the BUMP value 
correspond to sprites 1 through 8 respectively, BUMP(n) is reset 
to zero after each call. 


The value returned by BUMP is the result of two raised to the 
power of the bit position. For example, if BUMP returned a value 
of 16, sprite 4 was involved in a collision since 2 raised to the 
fourth power equals 16. 


EXAMPLES: 


PRINT BUMP (1) Indicates that sprites 2 and 3 have 
collided. 
12 


PRINT BUMP (2) Indicates that sprite 5 has 
collided with an object on the screen. 
32 


CHRS 
Return ASCII character for specified CBM ASCII code 
CHR$(X) 


This is the opposite of ASC and returns the string character 
whose CBM ASCII code is X. Refer to Appendix E for a table of 
CHR$ codes. 
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EXAMPLES: 


PRINT CHR$ (65) Prints the a character. 
a 


PRINT CHR$ (147) Clears the text screen. 


cos 
Return cosine for angle of X radians 
COS(X) 


This function returns the value of the cosine of X, where X is an 
angle measured in radians. 


EXAMPLE: 


PRINT COS (7) 
-1 


DEC 

Return decimal value of hexadecimal number string 
DEC (hexadecimal-string) 

This function returns the decimal value of hexadecimal-string. 
EXAMPLE: 


PRINT DEC (“D020”) 
53280 


F$=“F”:PRINT DEC(F$) 
15 


ERR$ 
Return the string describing an error condition 
ERR$(N) 


This function returns a string describing an error condition. Also 
see system variables EL and ER and Appendix A for a list of 
BASIC error messages. 
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EXAMPLE: 


PRINT ERR$(10) 
NEXT WITHOUT FOR 


EXP 


Return value of an approximation of e (2.7182813) raised to the 
power X 


EXP(X) 


This function returns a value of e (2.718281 3) raised to the power 
X. 


EXAMPLE: 


PRINT EXP(1) 
2.7182813 


FNxx 
Return value from user defined function 
FNxx(X) 


This function returns the value from the user-defined function xx 
created in a DEF FNxx statement. 


EXAMPLE: 


10 DEF FNAA(X)=(X-32)*5/9 

20 INPUT X 

30 PRINT FNAA(X) 

RUN 

? 40 (? is input prompt) 
444444445 


FRE 
Return number of available bytes in memory 
FRE (X) 
Where X is the bank number. X=0 BASIC program storage and 
X=1 to check for available BASIC variable storage. 
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EXAMPLES: 


PRINT FRE(0) Returns the number of free bytes for BASIC 
programs. 

48893 

PRINT FRE(1) Returns the number of free bytes for BASIC 


variable storage. 
64256 


HEX$ 

Return hexadecimal number string from decimal number 
HEX $(X) 

This function returns a four-character string containing the 


hexadecimal representation of value X (0 <= X < 65535). The 
decimal counterpart of this function is DEC. 


EXAMPLE: 


PRINT HEX$(53280) 
D020 
Note: HEX$(0) is “0000” 


INSTR 
Return position of string 1 in string 2 


INSTR (string 1, string 2 [,starting position]) 


The INSTR function searches for the first occurance of string 2 
within string 1, and returns the position within the string where the 
match is found. The optimal parameter for STARTING POSITION 
establishes the position in string 1 where the search begins. The 
STARTING POSTITION must be in the range 1 through 255. If no 
match is found or, if the STARTING POSITION is greater than the 
length of string 1 or if string 1 is null, INSTR returns the value O. If 
string 2 is null, INSTR returns 0. 


EXAMPLE: 


PRINT INSTR (“COMMODORE 128,128”) 
11 


157 


INT 


Return integer form (whole number part) of a floating point 
value 


INT(X) 
This function returns the integer value of the expression. If the 
expression Is positive, the fractional part is left out. If the 


expression |s negative, any fraction causes the next lower integer 
to be returned. 


EXAMPLES: 


PRINT INT(3.14) 
3 
PRINT INT(-3.14) 


JOY 

Return position of joystick and the status of the fire button 
JOY(N) 
When N equals: 


1 JOY returns position of joystick 1 
2 JOY returns position of joystick 2 


Any value of 128 or more means that the fire button is also 
pressed. To find the JOY value, add the direction value of the 
joystick plus 128, if the JOY fire button is pressed. The direction 
is indicated as follows: 


1 
8 2 
7 0 3 
6 4 
3) 


EXAMPLES: 


JOY (2) is 135 
When Joystick 2 fires to the left. 


IF (JOY (1) AND 128) = 128 THEN PRINT “FIRE’’. 
Determines whether the fire button is pressed. 
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LEFTS$ 
Return the leftmost characters of string 
LEFT$ (string,integer) 


This function returns a string comprised of the number of leftmost 
characters of the string determined by the specified integer. The 
integer argument must be in the range 0 to 255. If the integer is 
greater than the length of the string, the entire string is returned. lf 
an integer value of zero is used, then a null string (of zero length) 
is returned. 


EXAMPLE: 


PRINT LEFT$ (COMMODORE”,5) 
COMMO 


LEN 
Return the length of a string 
LEN (string) 


This function returns the number of characters in the string 
expression. Non-printed characters and blanks are included. 


EXAMPLE: 


PRINT LEN (“COMMODORE128”) 
12 


LOG 
Return natural log of X 
LOG(X) 


This function returns the natural log of X. The natural log is log to 
the base e (see EXP(X)). To convert to log base 10, divide by 
LOG(10). 


EXAMPLE: 


PRINT LOG (37/5) 
2.00148 
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MIDS 


Return a substring from a larger string or overlay a substring into 
a larger string 


MID$ (string,starting position[,length)) 


This function returns a substring specified by the LENGTH, 
Starting at the character specified by the starting position. The 
Starting position of the substring defines the first character where 
the substring begins. The length of the substring is specified by 
the length argument. Both of the numeric arguments can have 
values ranging from 0 to 255. If the starting position value is 
greater than the length of the string, or if the length value is zero, 
then MID$ returns a null string value. If the length argument is left 
out, all characters to the right of the starting position are returned. 


EXAMPLE: 


PRINT MID$(““COMMODORE 128,3,5) 
MMODO 


EXAMPLE using overlay: 


A$=“123456”":MID$(A$,3,2)=““ABCDE”:PRINT A$ 
12AB56 


Note: overlay cannot be used to expand the size of a string, thus 
in the example above MID$(A$,3,5) is not possible. 


PEEK 
Return contents of a specified memory location 
PEEK(X) 


This function returns the contents of memory location X, where X 
is located in the range 0 to 65535, returning a result between 0 
and 255. This is the counterpart of the POKE statement. The data 
will be returned from the bank selected by the most recent BANK 
command. See the BANK command. 


EXAMPLE: 


10 BANK 15:VIC=DEC(‘‘D000”) 
20 FORI=1T0 47 

30 PRINT PEEK(VIC + 1), 

40 NEXT 
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This example displays the contents of the registers of the VIC 
Chip. 


PEN 
Returns X and Y coordinates of the light pen 
PEN(n) 


where n=0 PEN returns the X coordinate of light pen position. 
n=1 PEN returns the Y coordinate of light pen position. 
n=2 PEN returns the X coordinate of the 80 column 
display. 
n=3 PEN returns the Y coordinate of the 80 column 
display. 
n=4 PEN returns the light pen trigger value. 


Note that, like sprite coordinates, the PEN value is not scaled and 
uses real coordinates, not graphic bit map coordinates. The X 
position is given as a number, ranging from approximately 60 to 
320, while the Y position can be any number from 50 to 250. 
These are the visible screen coordinate ranges, where all other 
values are not visible on the screen. A value of zero for either 
position means the light pen is off screen and has not triggered 
an interrupt since the last read. Note that COLLISION need not 
be active to use PEN. A white background is usually required to 
stimulate the light pen. PEN values vary from system to system. 


Unlike the 40 column (VIC) screen, the 80 column (8563) 
coordinates are character row and column positions and not pixel 
coordinates like the VIC screen. Both the 40 and 80 column 
screen coordinate values are approximate and vary, due to the 
nature of light pens. The read values are not valid until PEN(4) is 
true. 


EXAMPLES: 


10 PRINT PEN(0);PEN(1) Display the X and Y 
coordinates of the light pen. 


10 DO UNTIL PEN(4):LOOP Ensure the read values are 
20 X=PEN(2) valid. 

30 Y=PEN(3) 

40 REM:REST OF PROGRAM 
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T 


Returns the value of pi (3.14159265) 


7 
EXAMPLE: 
PRINT 7 
3.14159265 
POINTER 


Return the address of a variable name 
POINTER (variable name) 
EXAMPLE: 
PRINT POINTER (Z) 

This example returns the address of variable Z. 


POS 


Returns the current cursor column position within the current 
screen window 


POS(X) 


The POS function indicates where the cursor Is within the defined 
screen window. X is a dummy argument, which must be 
specified, but the value is ignored. 


EXAMPLE: 


PRINT “0123456789” POS(1) 
0123456789 10 


This displays the current cursor position within the defined text 
window, in this case 10. 


POT 
Returns the value of the game-paddle potentiometer 


POT (n) 
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when: 


n=1, POT returns the position of paddle #1 
n=2, POT returns the position of paddle #2 
n=3, POT returns the position of paddle #3 
n=4, POT returns the position of paddle #4 


The values for POT range from 0 to 255. Any value of 256 or 
more means that the fire button is also depressed. 


EXAMPLE: 


10 PRINT POT(1) 
20 IF POT(1) >=256 THEN PRINT “FIRE” 


This example displays the value of the game paddle 1. 


Note: a value of 255 is returned if no paddles are connected. 


RCLR 
Return color of color source 
RCLR(N) 
This function returns the color (1 to 16) assigned to the color 
source N (O< N < 6), where the following N values apply: 


0 = 40-column background 

1 = bit map foreground 

2 = multicolor 1 

3 = multicolor 2 

4 = 40-column border 

§ = 40- or 80-column character color 
6 = 80-column background color 


The counterpart to the RCLR function is the COLOR command. 
EXAMPLE: 


10 FORI=0TO6 
20 PRINT “SOURCE”;I;"IS COLOR CODE” ;RCLRi(I) 
30 NEXT 


This example prints the color codes for all seven color sources. 
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RDOT 
Return current position or color of pixel cursor. 


RDOT (N) 
where: 


N = 0 returns the X coordinate of the pixel cursor 
N = 1 returns the Y coordinate of the pixel cursor 
N = 2 returns the color source of the pixel cursor 


This function returns the location of the current position of the 
pixel cursor (PC) or the current color source of the pixel cursor. 


EXAMPLE: 

PRINT RDOT(O) Returns X position of PC 

PRINT RDOT(1) Returns Y position of PC 

PRINT RDOT(2) Returns color source of PC (0 to 3) 


RGR 
Return current graphic mode 


RGR(X) 


This function returns the current graphic mode. X is a dummy 
argument, which must be specified. Tne counterpart of the RGR 
function is the GRAPHIC command. The value returned by 
RGR(X) pertains to the following modes: 


VALUE GRAPHIC MODE 

40 column (VIC) text 
Standard bit map 

Split screen bit map 
Multicolor bit map 

Split screen Multicolor bit map 
80 column (8563) text 


EXAMPLE: 
PRINT RGR(0) 
1 


oh WN = © 


This displays the current graphic mode, in this case, standard bit 
map mode. 
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RIGHTS 
Return substring from rightmost end of string 
RIGHTS$ (<string>, <numeric>) 


This function returns a substring taken from the rightmost 
Characters of the string argument. The length of the substring is 
defined by the length argument which can be any integer in the 
range of 0 to 255. If the value of the numeric expression Is zero, 
then a null string is returned. If the value given in the length 
argument is greater than the length of the string, the entire string 
is returned, Also see the LEFT$ and MID$ functions. 


EXAMPLE: 
PRINT RIGHT$(‘“‘BASEBALL’’,5) 
EBALL 


RND 
Return a random number 
RND (X) 


This function returns a random number x, such thatO <= x <1. 
This is useful in games, to simulate dice roll and other elements 
of chance. It is also used in some statistical applications. 


lfX =0 RND returns a random number based on 
the hardware clock. 

lfX > 1 RND generates a reproducable psuedo- 
random number based on the seed value 
below. 

lfX< 0 produces a random number which is used 


as a base called a seed. 


To simulate the rolling of a die, use the formula INT(RND(1) * 6 + 
1). First the random number is multiplied by 6, which expands the 
range to 0-6 (actually, less than six). Then 1 is added, making the 
range from 1 to less than 7. The INT function truncates all the 
decimal places, leaving the result as a digit from 1 to 6. 
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EXAMPLES: 


PRINT RND(0) This displays a random 
507824123 number. 
PRINT INT(RND(1)*100 + 1) This displays a random 
89 positive number less than 100. 
RSPCOLOR 


Return sprite multicolor values 
RSPCOLOR (register) 
When: 


X= 1 RSPCOLOR returns the sprite multicolor 1 
X = 2 RSPCOLOR returns the sprite multicolor 2 


The returned color value is a value between 1 and 16. The 
counterpart of the RSPCOLOR function is the SPRCOLOR 
Statement. Also see the SPRCOLOR statement. 


EXAMPLE: 

10 SPRITE 1,1,2,0,1,1,1 

20 SPRCOLOR 5,7 

30 PRINT“SPRITE MULTICOLOR 1 1S’”;RSPCOLOR(1) 


40 PRINT“SPRITE MULTICOLOR 2 IS” ;RSPCOLOR(2) 
RUN 


SPRITE MULTICOLOR 1 IS 5 
SPRITE MULTICOLOR 2 |S 7 


In this example line 10 turns on sprite 1, colors it white, expands it 
in both the X and Y directions and displays it in multicolor mode. 
Line 20 selects sprite multicolors 1 and 2. Lines 30 and 40 print 
the RSPCOLOR values for multicolor 1 and 2. 


RSPPOS 
Return the speed and position values of a sprite 
RSPPOS (sprite number,X) 


where sprite number identifies which sprite is being checked, and 
X specifies X and Y coordinates or the sprite’s speed. 
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When x equals: 


0 RSPPOS returns the current X position of the specified 
sprite. 

1 RSPPOS returns the current Y position of the specified 
Sprite. 

2 RSPPOS returns the speed (0-15) of the specified sprite. 


EXAMPLE: 


10 SPRITE 1,1,2 
20 MOVSPR 1,45#13 
30 PRINT RSPPOS(1,0);RSPPOS(1,1);RSPPOS(1,2) 


This example returns the current X and Y sprite coordinates and 
the speed (13). 


RSPRITE 
Return sprite characteristics 
RSPRITE (sprite number,characteristic) 


RSPRITE returns sprite characteristics that were specified in the 
SPRITE command. Sprite number specifies the sprite you are 
checking and the characteristic specifies the sprite’s display 
qualities as follows: 


Characteristic RSPRITE returns 
these values: 


0 Enabled(1) / disabled(Q). 
1 Sprite color (1-16). 
2 Sprites are displayed in 


front of (O) or behind (1) 

objects on the screen. 

Expand in X direction yes =1, no=0. 
Expand in Y direction yes =1, no=0. 
Multicolor yes =1, no=0. 


um W 


EXAMPLE: 


10 FORI=0TO5 This example prints all 6 
20 PRINT RSPRITE (1,1) characteristics of sprite 1. 
30 NEXT 
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RWINDOW 

Returns the size of the current window 
RWINDOW (n) 

When n equals: 


0 RWINDOW returns the number of lines in the current 
window. 

1 RWINDOW returns the number of rows in the current 
window. 

2 RWINDOW returns either of the values 40 or 80, 
depending on the current screen output format you are 
USING. 


The counterpart of the RWINDOW function is the WINDOW 
command. 


EXAMPLE: 


10 WINDOW 1,1,10,10 
20 PRINT RWINDOW(0);RWINDOW(1);RWINDOW(2) 
RUN 

9 9 40 


This example returns the number of lines (9) and columns (9) in 
the current window. This example assumes you are displaying 
the window in 40 column format. 





SGN 
Return sign of argument X 
SGN(X) 


This function returns the sign,(positive, negative or zero) of X. The 
resultis +1 ifX > 0, O0ifX=0,and-1ifX<0. 


EXAMPLE: 


PRINT SGN(4.5);SGN(0);SGN(-2.3) 
1 0-1 
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SIN 
Return sine of argument X 
SIN(X) 


This is the trigonometric sine function. The result is the sine of X. 
X is measured in radians. 


EXAMPLE: 


PRINT SIN (7/3) 
866025404 


SPC 
Skip spaces on the screen 
SPC (X) 


This function is used in PRINT or PRINT# Commands to control 
the formatting of data, as either output to the screen or output to 
a logical file. The number of SPaCes specified by X determines 
the number of characters to fill with spaces across the screen or 
in a file. For screen or tape files, the value of the argument is in 
the range 0 to 255 and for disk files the maximum is 254. For 
printer files, an automatic carriage-return and line-feed will be 
performed by the printer if a SPaCe is printed in the last character 
position of a line. No SPaCes are printed on the following line. 


EXAMPLE: 


PRINT ‘““COMMODORE”’;SPC(3);“128” 
COMMODORE 128 


SQR 
Return square root of argument 
SQR (X) 


This function returns the value of the SQuare Root of X, where X 
is a positive number or 0. The value of the argument must not be 
negative, or the BASIC error message ?ILLEGAL QUANTITY is 
displayed. 
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EXAMPLE: 
PRINT SQR(25) 
5 


STR$ 
Return string representation of number 
STR$ (X) 


This function returns the STRing representation of the numeric 
value of the argument X. When the STR$ value is converted, any 
number displayed is preceded and followed by a space except 
for negative numbers which are preceded by a minus sign. The 
counterpart of the STR$ function is the VAL function. 


EXAMPLE: 


PRINT STR$(123.45) 
123.45 


PRINT STRS$(-89.03) 
-89.03 


PRINT STR$(1E20) 
1E+20 


TAB 
Moves cursor to tab position in present statement 
TAB (X) 


This function moves the cursor forward if possible to a relative 
position on the text screen given by the argument X, starting with 
the left-most position of the current line. The value of the 
argument can range from 0 to 255. If the current print position is 
already beyond position X, the TAB command is ignored. The 
TAB function should only be used with the PRINT statement, 
since it has varied effects if used with the PRINT# to a logical file 
depending on the device being used. 


EXAMPLE: 
10 PRINTCOMMODORE’” TAB(25)‘‘128” 
COMMODORE 128 
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TAN 
Return tangent of argument 
TAN(X) 


This function returns the tangent of X, where X is an angle in 
radians. 


EXAMPLE: 
PRINT TAN(.785398163) 
1 


USR 
Call user-defined subfunction 
USR(X) 


When this function is used, the program jumps to a machine 
language program whose starting point is contained in memory 
locations 4633($1219) and 4634($121A), (or 785($0311) and 
786($0312) for C64 mode). The parameter X is passed to the 
machine language program in the floating point accumulator. A 
value is returned to the BASIC program through the calling 
variable. You must redirect the value into a variable in your 
program in order to receive the value back from the floating point 
accumulator. An ILLEGAL QUANTITY ERROR results if you don't 
specify this variable. This allows the user to exchange a variable 
between machine code and BASIC. 


EXAMPLE (128 Only): 


10 POKE 4633,0 

20 POKE 4634,192 Note: default 128 bank 15. 
30 A = USR(X) 

40 PRINTA 


Place starting location (SCO00=491 52:$00=0:$C0=1 92) of 
machine language routine in location 4633 and 4634. Line 30 
stores the returning value from the floating point accumulator. 
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VAL 
Return the numeric value of a number string 
VAL(X$) 


This function converts the string X$ into a number. It is the 
inverse operation of STR$. The string is examined from the left- 
most character to the right, for as many Characters as are in 
recognizable number format. If the Commodore 128 finds illegal 
Characters, only the portion of the string up to that point is 
converted. If no numeric Characters are present, VAL returns a 0. 


EXAMPLE: 


10 A$ = “120” 
20 B$ = “365” 
30 PRINT VAL (A$) + VAL(BS$) 
RUN 
485 


XOR 
Return exclusive OR 
XOR (n1,n2) 


This function provides the exclusive OR of the argument values 
ni and nz. 


x = XOR (n1,n2) 
where n1, n2, are 2 unsigned values (0-65535). 
EXAMPLE: 


PRINT XOR(128,64) 
192 


Note: ni and n2 need not be whole numbers. 
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SECTION 19 


Variables and Operators 


MPS es ose ost ich ces oe es Ee te oh oeenioes 
OPERATORS ..ciaducee si bors caiaesiseseieevexaaesoudsenieeess 


VARIABLES 


The Commodore 128 uses three types of variables in BASIC. 
These are: normal numeric, integer numeric and string 
(alphanumeric). 


Normal NUMERIC VARIABLES, also called floating point 
variables, can have any exponent value from -10 to +10, with up 
to nine digits of accuracy. When a number becomes larger than 
nine digits can show, the computer displays it in scientific 
notation form, with the number normalized to one digit and eight 
decimal places, followed by the letter E and the power of 10 by 
which the number is multiplied. For example, the number 
12345678901 is displayed as 1.23456789E+10. 


INTEGER VARIABLES can be used when the number is from 
+32767 to -32768, and with no fractional portion. An integer 
variable is a number like 5, 10 or -100. Integers take up less 
space than floating point variables, particularly when used in an 
array. 


STRING VARIABLES are those used for character data, which 
may contain numbers, letters and any other characters the 


Commodore 128 can display. An example of a string variable is 
“COMMODORE 128”. 


VARIABLE NAMES may consist of a single letter, a letter followed 
by a number, or two letters. Variable names may be longer than 
two characters, but only the first two are significant. An integer is 
specified by using the percent sign (%) after the variable name. 
String variables have a dollar sign ($) after their names. 


EXAMPLES: 


Numeric Variable Names: A, A5, BZ 
Integer Variable Names: A%, A5%, BZ% 
String Variable Names: A$, A5$, BZ$ 


ARRAYS are lists of variables with the same name, using an extra 
number (or numbers) to specify an element of the array. Arrays 
are defined using the DIM statement and may be floating point, 
integer or string variable arrays. The array variable name is 
followed by a set of parentheses () enclosing the number of the 
variable in the list. 
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EXAMPLE: 
A(7), BZ%(11), A$(87) 


Arrays can have more than one dimension. A two-dimensional 
array may be viewed as having rows and columns, with the first 
number identifying the row and the second number identifying the 
column (as if specifying a certain grid on the map). 


EXAMPLE: 
A(7,2), BZ%(2,3,4), 2$(3,2) 


RESERVED VARIABLE NAMES are names reserved for use by 
the Commodore 128, and may not be used for another purpose. 
These are the variables DS, DS$, ER, ERR$, EL, ST, TI and TI$. 
KEYWORDS such as TO and IF or any other names that contain 
KEYWORDS, such as RUN, NEW or LOAD cannot be used. 


ST is a status variable for input and output (except normal 
screen/keyboard operations). The value of ST depends on the 
results of the last |/O operation. In general, if the value of ST is 0, 
then the operation was successful. 


Tl and TI$ are variables that relate to the real time clock built into 
the Commodore 128. The system clock is updated every 1/60th 
of a second. It starts at 0 wnen the Commodore 128 is turned on, 
and is reset only by changing the value of TI$. The variable T| 
gives the current value of the clock in 1/60th of a second. TI$ is 
a string that reads the value of the real time clock as a 24-hour 
clock. The first two characters of TI$ contain the hour, the third 
and fourth characters are minutes and the fifth and sixth 
Characters are seconds. This variable can be set to any value (so 
long as all characters are numbers) and will be updated 
automatically as a 24-hour clock. 


EXAMPLE: 


TI$ = “101530” sets the clock to 10:15 and 30 seconds 
(AM) 


The value of the clock is lost when the Commodore 128 is turned 
off. It starts at zero when the Commodore 128 is turned on, and Is 
reset to zero when the value of the clock exceeds 235959 (23 
hours, 59 minutes and 59 seconds). 
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The variable DS reads the disk drive command channel and 
returns the current status of the drive. To get this information in 
words, PRINT DS$. These status variables are used after a disk 
operation, like DLOAD or DSAVE, to find out why the red error 
light on the disk drive is blinking. 


ER, EL and ERR$ are variables used in error trapping routines. 
They are usually only useful within a program. ER returns the last 
error encountered since the program was RUN. EL is the line 
where the error occurred. ERR$ is a function that allows the 
program to print one of the BASIC error messages. PRINT 
ERR$(ER) prints out the proper error message. 


OPERATORS 


The BASIC OPERATORS include ARITHMETIC, RELATIONAL 
and LOGICAL OPERATORS. The ARITHMETIC operators include 
the following signs: 


+ addition 

- subtraction 

* multiplication 

/ division 

t raising to a power (exponentiation) 


On a line containing more than one operator, there is a set order 
in which operations always occur. If several operators are used 
together, the computer assigns priorities as follows: First, 
exponentiation, then multiplication and division, and last, addition 
and subtraction. If two operators have the same priority, then 
calculations are performed in order from left to right. If these 
operations are to occur in a different order, Commodore 128 
BASIC allows giving a calculation a higher priority by placing 
parentheses around it. Operations enclosed in parentheses will 
be calculated before any other operation. Make sure the 
equations have the same number of left and right parentheses, or 
a SYNTAX ERROR message is displayed when the program is 
run. 
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There are also operators for equalities and inequalities, called 
RELATIONAL operators. Arithmetic operators always take priority 
over relational operators. 


= is equai to 

< is less than 

is greater than 
<=or=< is less than or equal to 
>=or=> is greater than or equal to 
<>or>< is not equal to 


Finally, there are three LOGICAL operators, with lower priority 
than both arithmetic and relational operators: 


These are most often used to join multiple formulas in IF ... THEN 
statements. When they are used with arithmetic operators, they 
are evaluated last (i.e., after + and -). If the relationship stated in 
the expression is true, the result is assigned an integer value of - 
1. If false, a value of O is assigned. 


EXAMPLES: 


IF A=B AND C=D THEN 100 Requires both A=B & 
C=D to be true 


IF A=B OR C=D THEN 100 Allows either A=B, C=D, 
or both, to be true 

A=5:B=4:PRINT A=B Displays a value of 0 

A=5:B=4:PRINT A>3 Displays a value of -1 


PRINT 123 AND 15:PRINT 5 OR7 Displays 11 and 7 
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SECTION 20 


Reserved Words and Symbols 


RESERVED SYSTEM WORDS (KEYWORDS) 


RESERVED SYSTEM SYMBOLS ............. 


a 
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RESERVED SYSTEM WORDS (KEYWORDS) 


This section lists the words and symbols used to make up the 
BASIC 7.0 language. These words and symbols cannot be used 
within a program as other than a component of the BASIC 

language. The only exception is that they may be used within 
quotes in a PRINT statement. 


ABS 
AND 
APPEND 
ASC 
ATN 
AUTO 
BACKUP 
BANK 
BEGIN 
BEND 
BLOAD 
BOOT 
BOX 
BSAVE 
BUMP 
CATALOG 
CHAR 
CHR$ 
CIRCLE 
CLOSE 
CLR 
CMD 
COLLECT 
COLLISION 
COLOR 
CONCAT 
CONT 
COPY 
COS 
DATA 
DCLEAR 
DCLOSE 
DEC 
DEF 
DELETE 


* OFF and QUIT are unimplemented. 


DIM 
DIRECTORY 
DLOAD 

DO 

DOPEN 
DRAW 

DS 

DSAVE 

DS$ 
DVERIFY 


ENVELOPE 
ER 
ERR$ 
EXIT 
EXP 
FAST 
FETCH 
FILTER 
FN 

FOR 
FRE 
GET 
GETKEY 
GET# 
GO64 
GOSUB 
GOTO 
GO TO 
GRAPHIC 
GSHAPE 
HEADER 
HELP 


HEX$ 

IF 
INPUT 
INPUT# 
INSTR 
INT 
JOY 
KEY 
LEFT$ 
LEN 
LET 
LIST 
LOAD 
LOCATE 
LOG 
LOOP 
MIDS 
MONITOR 
MOVSPR 
NEW 


PLAY 
POINTER 
POKE 
POS 
POT 
PRINT 


PRINT# 
PUDEF 
QUIT* 
RCLR 
RDOT 
READ 
RECORD 
REM 
RENAME 
RENUMBER 
RESTORE 
RESUME 
RETURN 
RGR 
RIGHT$ 
RND 
RREG 
RSPCOLOR 
RSPPOS 
RSPRITE 
RUN 
RWINDOW 
SAVE 
SCALE 
SCNCLR 
SCRATCH 
SGN 

SIN 
SLEEP 
SLOW 
SOUND 
SPC( 
SPRCOLOR 
SPRDEF 
SPRITE 


SPRSAV 
SQR 


WINDOW 


XOR 
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RESERVED SYSTEM SYMBOLS 
The following characters are reserved system symbols. 


+ 
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Symbol 


Plus sign 


Minus sign 


Asterisk 
Slash 
Up arrow 


Blank space 


Equal sign 


Less than 
Greater than 


Comma 


Period 


Semicolon 


Colon 


Quotation mark 
Question mark 
Left parenthesis 


Right parenthesis 


Percent 


Use(s) 


Arithmetic addition; string 
concatenation; relative 
sprite movement; declare 
decimal number in machine 
language monitor 


Arithmetic subtraction; negative 
number; unary minus; relative 
sprite movement 


Arithmetic multiplication 
Arithmetic division 
Arithmetic exponentiation 


Separate keywords and variable 
names 


Value assignment: relationship 
testing 


Relationship testing 
Relationship testing 


Format output in variable 
lists; command/statement 
function parameters 


Decimal point in floating point 
constants 


Format output in variable lists 


Separate multiple BASIC 
statements on a program line 


Enclose string constants 

Abbreviation for the keyword PRINT 
Expression evaluation and functions 
Expression evaluation and functions 


Declare a variable name as integer; 
declare binary number in machine 
language monitor 


Hash 


Dollar sign 


And sign 


Pi 


Precede the logical file number in 
input/output statements 


Declare a variable name as a string 
and declares hexadecimal number in 
machine language monitor 


Declare octal number in machine 
language monitor 


Declare the numeric constant — 
approximately 3.14159265 


APPENDICES 


APPENDIX 
APPENDIX 
APPENDIX 


APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 
APPENDIX 


Pr eS 2G? TT SB QOwLr 


BASIC LANGUAGE ERROR MESSAGES 
DOS ERROR MESSAGES 
CONNECTORS/PORTS FOR PERIPHERAL 
EQUIPMENT 

SCREEN DISPLAY CODES 

ASCII AND CHR$ CODES 

SCREEN AND COLOR MEMORY MAPS 
DERIVED MATHEMATICAL FUNCTIONS 
MEMORY MAP 

CONTROL AND ESCAPE CODES 
MACHINE LANGUAGE MONITOR 
BASIC 7.0 ABBREVIATIONS 

DISK COMMAND SUMMARY 


APPENDIX A 
BASIC LANGUAGE ERROR 
MESSAGES 


The following error messages are displayed by BASIC. Error 
messages can also be displayed with the use of the ERR$() 
function. The error numbers below refer only to the number 

assigned to the error for use with the ERR$() function. 


ERROR # ERROR NAME DESCRIPTION 
1 TOO MANY FILES There is a limit of 10 
files OPEN at one time. 
2 FILE OPEN An attempt was made to 


open a file using the 
number of an already 
open file. 


3 FILE NOT OPEN The file number 
specified in an |/O 
statement must be 
opened before use. 


4 FILE NOT FOUND Either no file with that 
name exists (disk) or 
an end-of-tape marker 
was read (tape). 


o DEVICE NOT PRESENT The required |/O device is 
not available or buffers 
deallocated (cassette). 
Check to make sure device 
is connected and turned on. 


6 NOT INPUT FILE An attempt was made to GET 
or INPUT data from a 
file that was specified 
as Output only. 
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NOT OUTPUT FILE 


MISSING FILE NAME 


ILLEGAL DEVICE 
NUMBER 


NEXT WITHOUT FOR 


SYNTAX 


RETURN WITHOUT 
GOSUB 


OUT OF DATA 


ILLEGAL QUANTITY 


OVERFLOW 


OUT OF MEMORY 


An attempt was made to 
send data to a file 

that was specified as 
input only. 


File name missing in 
command. 


An attempt was made to use 
a device improperly (SAVE 
to the screen, etc.). 


Either loops are nested 
incorrectly, or there 

is a variable name in a 
NEXT statement that 
doesn't correspond with 
one in FOR. 


A statement not recognized 
by BASIC. This could be 
because of a missing or 
extra parenthesis, mis- 
spelled key word, etc. 


A RETURN statement was 
encountered when no GOSUB 
statement was active. 


A READ statement was 
encountered without data 
left UNREAD. 


A number used as the 
argument of a function 
or statement is outside 
the allowable range. 


The result of a computa- 
tion is larger than the 
largest number allowed 
(1.701411833E+38). 


Either there is no 
more room for program 
code and/or program 
variables, or there 


ae 


23 


24 


po 


26 


UNDEF'D STATEMENT 


BAD SUBSCRIPT 


REDIM'’D ARRAY 


DIVISION BY ZERO 


ILLEGAL DIRECT 


TYPE MISMATCH 


STRING TOO LONG 


FILE DATA 


FORMULA TOO 
COMPLEX 


CAN'T CONTINUE 


are too many nested 
DO, FOR or GOSUB 
statements in effect. 


A line number refer 
enced doesn't exist 
in the program. 


The program tried to 

reference an element 

of an array out of the 
range specified by the 
DIM statement. 


An array can only be 
DiMensioned once. 


Division by zero is not 
allowed. 


INPUT or GET, or INPUT# 
or GET# statements are 
only allowed within 

a program. 


This occurs when a 
numeric value is used 
in place of a string or 
vice versa. 


A string can contain up 
to 255 characters. 


Bad data read from a 
tape or disk file. 


The computer was unable 
to understand this 
expression. Simplify 

the expression (break 

into two parts or use 
fewer parentheses). 


The CONT command does 
not work if the program 
was not RUN, there was 
an error, or a line had 
been edited. 
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28 


29 


30 


| 


32 


33 


34 


35 


36 
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UNDEFINED FUNCTION A user-defined function 


VERIFY 


LOAD 


BREAK 


CAN'T RESUME 


LOOP NOT FOUND 


LOOP WITHOUT DO 


DIRECT MODE ONLY 


NO GRAPHICS AREA 


BAD DISK 


was referenced that was 
never defined. 


The program on tape or 
disk does not match the 
program in memory. 


There was a problem 
loading. Try again. 


The stop key was hit to 
halt program execution. 


A RESUME statement was 
encountered without a TRAP 
statement in effect. 


The program has 
encountered a DO 
statement and cannot 
find the corresponding 
LOOP. 


LOOP was encountered with- 
out a DO statement active. 


This command its allowed 
only in direct mode, not 
from a program. 


A command (DRAW, BOX, 
etc.) to create graphics 
was encountered before the 
GRAPHIC command was 
executed. 


An attempt failed to 
HEADER a diskette, 
because the quick header 
method (no ID) was 
attempted on an 
unformatted diskette or 
the diskette is bad. 


37 


38 


39 


40 


41 


BEND NOT FOUND 


LINE # TOO LARGE 


UNRESOLVED 
REFERENCE 


UNIMPLEMENTED 
COMMAND 


FILE READ 


The program encountered 
an “IF..THEN BEGIN “ or 
“IF... THEN...ELSE BEGIN” 
construct, and could not 

find a BEND keyword to 

match the BEGIN. 


An error has occurred in 
renumbering a BASIC 
program. The given 
parameters result in a 

line number > 63999 being 
generated; therefore, the 
renumbering was not 
performed. 


An error has occurred in 
renumbering a BASIC pro- 
gram. A line number referred 
to by acommand (e.g., GOTO 
999) does not exist. 
Therefore the renumbering 
was not performed. 


A command not supported by 
BASIC 7.0 was encountered. 


An error condition was 
encountered while loading 
or reading a program or 
file from the disk drive 
(e.g., opening the disk 
drive door while a program 
was loading). 
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APPENDIX B 
DOS ERROR MESSAGES 


The following error messages are returned through the DS and 
DS$ variables. The DS variable contains just the error number 
and the DS$ variable contains the error number, the error 
message and any corresponding track and sector number. 
NOTE: Error message numbers less than 20 should be ignored 
with the exception of 01, which gives information about the 
number of files scratched with the SCRATCH command. 


ERROR = ERROR MESSAGE AND 
NUMBER DESCRIPTION 


20: READ ERROR (block header not found) 
The disk controller is unable to locate the 
header of the requested data block. Caused 
by an illegal sector number, or the header 
has been destroyed. 


21: READ ERROR (no sync character) 
The disk controller is unable to detect a sync 
mark on the desired track. Caused by 
misalignment of the read/write head, no diskette 
is present, or unformatted or improperly seated 
diskette. Can also indicate a hardware failure. 


22. READ ERROR (data block not present) 
The disk controller has been requested to read 
or verify a data block that was not properly 
written. This error occurs in conjunction 
with the BLOCK commands and indicates an illegal 
track and/or sector request. 


os READ ERROR (checksum error in data block) 
This error message indicates there is an 
error in one or more of the data bytes. The 
data has been read into the DOS memory, but 
the checksum over the data is in error. This 
message may also indicate hardware grounding 
problems. 
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24: 


25: 


26: 


27: 


28: 


29: 


30: 


31: 
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READ ERROR (byte decoding error) 

The data or header has been read into the DOS 
memory but a hardware error has been created 
due to an invalid bit pattern in the data byte. 
This message may also indicate grounding 
problems. 


WRITE ERROR (write-verify error) 

This message is generated if the controller 
detects a mismatch between the written data 
and the data in the DOS memory. 


WRITE PROTECT ON 

This message is generated when the controller 
has been requested to write a data block while 
the write protect switch is depressed. This is 
caused by using a diskette with a write protect 
tab over the notch. 


READ ERROR (checksum error in header) 

This message is generated when a checksum error 
has been detected in the header of the requested 
data block. The block has not been read into 

DOS memory. 


WRITE ERROR (long data block) 

This error message is generated when a data 
block is too long and overwrites the sync mark 
of the next header. 


DISK ID MISMATCH 

This message is generated when the controller 
has been requested to access a diskette which 
has not been initialized. The message can also 
occur if a diskette has a bad header. 


SYNTAX ERROR (general syntax) 

The DOS cannot interpret the command sent to the 
command channel. Typically, this is caused by 

an illegal number of file names, or patterns are 
illegally used. For example, file names appear 

on the left side of the COPY command. 


SYNTAX ERROR (invalid commana) 
The DOS does not recognize the command. The 
command must start in the first position. 


32. 


33: 


34: 


39: 


50: 


51: 


Be: 


60: 


SYNTAX ERROR (long line) 
The command sent is longer than 58 characters. 
Use abbreviated disk commands. 


SYNTAX ERROR (invalid file name) 
Pattern matching is invalidly used in the OPEN 
or SAVE command. Spell out the file name. 


SYNTAX ERROR (no file given) 

The file name was left out of the command or the 
DOS does not recognize it as such. Typically, 

a colon (:) has been left out of the commana. 


SYNTAX ERROR (invalid command) 

This error may result if the command sent to the 
command channel (secondary address 15) is 
unrecognized by the DOS. 


RECORD NOT PRESENT 

Result of disk reading past the last record 

through INPUT# or GET# commands. This message 
will also occur after positioning to a record 

beyond end-of-file in a relative file. If the 

intent is to expand the file by adding the new 

record (with a PRINT# commana), the error 
message may be ignored. INPUT# and GET# 
should not be attempted after this error is detected 
without first repositioning. 


OVERFLOW IN RECORD 

PRINT# statement exceeds record boundary. 
Information is truncated. Since the carriage 
return which is sent as a record terminator is 
counted in the record size, this message will 
occur if the total characters in the record 
(including the final carriage return) exceeds 
the defined size of the record. 


FILE TOO LARGE 
Record position within a relative file indicates 
that disk overflow will result. 


WRITE FILE OPEN 
This message is generated when a write file that 
has not been closed is being opened for reading. 
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62: 


63: 


64: 


65: 


66: 


67: 


70: 
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FILE NOT OPEN 

This message is generated when a file is being 
accessed that has not been opened in the DOS. 
Sometimes, in this case, a message is not 
generated; the request is simply ignored. 


FILE NOT FOUND 
The requested file does not exist on the 
indicated drive. 


FILE EXISTS 
The file name of the file being created already 
exists on the diskette. 


FILE TYPE MISMATCH 

The requested file access is not possible using 
files of the type named. Reread the chapter 
covering that file type. 


NO BLOCK 

Occurs in conjunction with Block Allocation. The 
sector you tried to allocate is already allocated. 
The track and sector numbers returned are the 
next higher track and sector available. If the 
track number returned is zero (Q), all remaining 
sectors are full. If the diskette is not full 

yet, try a lower track and sector. 


ILLEGAL TRACK AND SECTOR 

The DOS has attempted to access a track or block 
which does not exist in the format being used. 
This may indicate a problem reading the pointer 

of the next block. 


ILLEGAL SYSTEM T ORS 
This special error message indicates an illegal 
system track or sector. 


NO CHANNEL (available) 

The requested channel is not available, or all 
channels are in use. A maximum of five buffers 
are available for use. A sequential file requires 
two buffers; a relative file requires three 

buffers; and the error/command channel requires 
one buffer. You may use any combination of 
those as long as the combination does not exceed 
five buffers. 


71: 


72: 


73: 


74: 


DIRECTORY ERROR 

The BAM (Block Availability Map) on the diskette 
does not match the copy on disk memory. To 
correct, initialize the diskette. 


DISK FULL 

Either the blocks on the diskette are used or 
the directory is at its entry limit. DISK 

FULL is sent when two blocks are still available 
on the diskette, in order to allow the current 

file to be closed. 


DOS MISMATCH (VERSION NUMBER) 

DOS 1 and 2 are read compatible but not write 
compatible. Disks may be interchangeably read 
with either DOS, but a disk formatted on one 
version Cannot be written upon with the other 
version because the format is different. This 
error is displayed whenever an attempt is made 
to write upon a disk which has been formatted 
in a non-compatible format. This message will 
also appear after power up and is not an error 
in this case. 


DRIVE NOT READY 

An attempt has been made to access the disk 
drive without any inserted; or the drive lever 
or door is open. 
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APPENDIX C 128 D 
CONNECTORS/PORTS FOR 
PERIPHERAL EQUIPMENT 


KEYBOARD CONNECTION 
SOCKET 


CONTROL PORT 1 
CONTROL PORT 2 


RESET SWITCH 


DISK DRIVE 
RESET SWITCH 





EXPANSION PORT 
CASSETTE PORT 
SERIAL SOCKET 
VIDEO SOCKET 


POWER SUPPLY 
USER PORT 
RGBI SOCKET 
RF SOCKET 





APPENDIX C 128 


CONNECTORS/PORTS FOR 
PERIPHERAL EQUIPMENT 
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Side Panel Connections 


1. Power Socket—The five pin square plug from the 
power supply is connected here. 


Power Switch—Turns on power from the power supply. 
Reset Button—Resets computer (warm start). 


Controller Ports—There are two Controller ports, 
numbered 1 and 2. Each Controller port can accept 
a joystick or game controller paddle. The light pen 
can be plugged only into port 1, the port closest to 
the front of the computer. Use the ports as 
instructed with the software. 


Control Port 1 


Type 


JOYAO 

JOYAI 

JOYA2 

JOYA3 

POT AY 

BUTTON A/LP 

+5V MAX. 50mMA 
GND 

POT Ax 


OMNI OO fWNH 





ART WORD AT THE SIDE OF THE ABOVE TABLE 


Control Port 2 


Type 


JOYBO 

JOYB1 

JOYB2 

JOYB3 

POT BY 

BUTTON B 

+5V MAX. 50mA 
GND 

POT BX 





i 
2 
3 
4 
5 
6 
7 
8 
9 
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Rear Connections 


5. Expansion Port—This rectangular slot ts a parallel 
port that accepts programs or game cartridges as 


well as special interfaces. 


Cartridge Expansion Slot 





N 
Pp 
R 
iS) 
T 
U 
V 
W 
xX 
Y 
Z 


22 21201918 1716181413 1211109 87654921 


ZYXWVUTSRPNMLEKJIHF EOC BA 


OOMON DOB WM = 


-+- 2 


ZSreAcTIMMIVODY 


GND 
+5V 
+5V 
TRO 
R/W 
Dot Clock 
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6. Cassette Port—A 1530 Datassette recorder can be 
attached here to store programs and information. 


Cassette 


123 4 5 6 
+5V 
CASSETTE MOTOR 


CASSETTE WRITE 
CASSETTE SENSE 





7. Serial Port—A Commodore Serial printer or disk 
drive can be attached directly to the Commodore 
128 through this port. 


Serial 1/O 


SERIAL SRQIN 
GND 


SERIAL ATN IN/OUT 
SERIAL CLK IN/OUT 


SERIAL DATA IN/OUT 
RESET 





Note: The Commodore Serial Port is not RS-232 compatible. 
TTL RS-232 levels can be obtained from the User Port. 
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8. 40 Column Video Connector—This DIN connector provides 
audio and composite video signals which can be 
directly connected to suitable audio and monitor 
equipment. These signals can be connected to the 
Commodore monitor or used with separate components. 


LUM/SYNC Luminance/SYNC output 
GND 

AUDIO OUT 

VIDEO OUT Composite signal output 
AUDIO IN 

COLOR OUT Chroma signal output 
NC No connection 

NC No connection 


1 
2 
3 
4 
5 
6 
7 
8 





9. RF Connector—This connector supplies both picture 
and sound to your television set. (A television can 
display only a 40 column picture.) 


10. 80 Column RGBI Connector—This 9-pin connector supplies 
direct audio and an RGBI (Red/Green/Blue/Intensity) 
signal. 
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Ground 
Ground 
Red 
Green 


Blue 

Intensity 
Monochrome 
Horizontal Syne 
Vertical Sync 


woman nnrFrwWwnr - 





11. User Port—Various interface devices can be attached 


here. 
User I/O 


GND 

+5V MAX. 100 mA 
RESET 

CNT1 

SP1 

CNT2 

SP2 

PC2 

SER. ATN IN 

9 VAC MAX. 100 mA 
9 VAC MAX. 100 mA 


OMOnN DNS WH = 


A 
B 
C 
D 
E 
F 
H 
J 
K 
L 
M 
N 





123 45 6 7 8 9 10 11 12 


Ceenaeneese! 


ABCOEFHJSKLOMN 
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APPENDIX D 


SCREEN DISPLAY CODES—40 
Columns 


The following chart lists all of the characters built into the 
Commodore screen character sets. It shows which numbers 
should be POKEd into screen memory (location 1024 to 2023) to 
get a desired character on the 40-column screen. (Remember, to 
set color memory, use locations 55296 to 56295.) Also shown is 
which character corresponds to a number PEEKed from the 
screen. 


Two character sets are available. Both are available 
simultaneously in 80-column mode, but only one is available at a 
time in 40-column mode. The sets are switched by holding down 
the SHIFT and & (Commodore) keys simultaneously. 


From BASIC, PRINT CHR$(142) will switch to upper- 
case/graphics mode and PRINT CHR$(14) will switch to 
upper/lower-case mode. 


Any number on the chart may also be displayed in REVERSE. 
The reverse character code may be obtained by adding 128 to 
the values shown. 





ET 
@ 0 £ 28 
A a 1 ] 29 
B b 2 ‘ 30 
C c 3 = 31 
D d 4 32 
E e 5 ! 33 
F f 6 34 
G g 7 # 35 
H h 8 $ 36 





37 


% 


24 
25 


39 


26 


*=Soao 88 Se BBBBSBLEENOMOSTHEBEREAO|MOR ET NR S 
tT oO Oo OO OO 9 Oo 89 Oo CO KF KF KF Ke Kr Kr rT rl rll KrlUC NN NNN 
be ce ee ee ee oe ce ee oe oe, oe oe, ee ee oe ee oe oe oe ee oe oe 


S S) 
“OURO NOARSM GOSH ERO AOU 





~ on DO OD - N © wo ~ @©® N 
yn CF XPRFKRRKRRGaSKGCRSSKBHKETESEBSRSBSHSS SB 
OoOr-r7xx* 6483s 200 OCaH4H#rFDF>FBEXKXO>N Be 


[ 


HAGRAINOVMNODSBOROCN KOA ha See) 


13 


or NO tT YO Oo KR w wD 
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DIOWW 


Cc 67 96 | BI 125 
D 68 7 a7 126 
E 69 = 98 iy 127 
F 70 a 99 


Codes from 128-255 are reversed images of codes 0-127. 


D-3 


APPENDIX E 
ASCII AND CHR$ CODES 


This appendix shows you what characters will appear if you 
PRINT CHRS(X), for all possible values of X. It also shows the 
values obtained by typing PRINT ASC(‘‘x”), where x is any 
character that can be displayed. This is useful in evaluating the 
Character received in a GET statement, converting upper to lower 
case and printing character-based commands (like switch to 
upper/lower case) that could not be enclosed in quotes. 










PRINTS CHRS$ 























0 
1 F 
2 G 
3 1 H 
4 27 2 73 
pwn J 5| Z- 8 3 J 74 
6 29 4 K 75 
7) 30 5 L 76 
osmesmgs | Ai 31 6 54 M 
enases EGO 32 7 55 NN 78 
10 | 33 8 O 
11 i 34 9 P 
12 # 35 Q 81 
13 $ 36 R 82 
14| % 37 S 83 
15 & 38 T 84 
16 39 U 85 
a 17 ( 40 V 86 
FA 8 ) 41 W 87 
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PRINTS CHRS | PRINTS CHARS | PRINTS CHRS | PRINTS CHRS 


q 
be. 





[ 








19 42 A 65 X 88 
20 + 43 B 66 Y 89 
= C 67 Z 90 
22 = 45 D 68 91 
92) Ov 115 | £4 138| Qf] 161 
93 [ 116 6 139 | fl =: 162 
a | JA 117 | 8 140} [ ] 163 
95 xX 116 | MUR GD 141 L} 164 
9 | O 119 142/ [| 165 
97 | [* 120 143 | Be 166 
9 | LI 121 | BEA 144) CI st687 
99 | 1%) 122 145| fe 168 
10 | Hoa) BA 146) FF t69 
101 | I) 124 147| ([]} 170 
102 LH 125 148 a 171 
103 126 | Brown 149 us 172 
14 | (™ 127 | Lt. Red 150 4 173 
105 128 | Dk. Gray 151 nl 174 
106 Orange 129 | Gray 152 = 175 
107 130 | Lt. Green153 io 176 
108 131 | Lt. Blue 154] FY 177 
109 132 | Lt.Gray 155] Ho 178 
110 1 133 four J 156 Hi 4179 
111 13 134 157 [) 180 
112 5 135 | ZA 158 E) 181 
13] 17 «136) MA 159| CE 182 
114 f2 137 160| (7) 183 


PRINTS CHRS$ | PRINTS CHRS$ | PRINTS CHRS | PRINTS CHRS 





CODES 192-223 SAME AS 96-127 
CODES 224-254 SAME AS 160-190 
CODE 255 SAME AS 126 


NOTE: The above codes are for C64 mode. See Appendix | for 
special codes in C128 mode. 
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APPENDIX F 

SCREEN AND COLOR MEMORY 
MAPS—C128 Mode, 40 Column and 
C64 Mode 


The following maps display the memory locations used in 40- 
column mode (C128 and C64) for identifying the characters on 
the screen as well as their color. Each map is separately 
controlled and consists of 1,000 positions. 


The character displayed on the maps can be controlled directly 
with the POKE command. 


SCREEN MEMORY MAP 


COLUMN 
20 




























































































EERERRERARE 
PELE TTT Ty) ee 




















The Screen Map is POKEd with a Screen Display Code value 
(see Appendix D). For example: 


POKE 1024, 13 


will display the letter M in the upper-left corner of the screen. 


COLOR MEMORY MAP 


COLUMN 

















a a 
PE TT Ty yi 















































If the color map is POKEd with a color value; this changes the 
character color. For example: 


POKE 55296, 1 
will change the letter M inserted above from light green to white. 
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NOOB WM —- © 


Black 
White 
Red 
Cyan 
Purple 
Green 
Blue 
Yellow 


Color Codes—40 Columns 


8 

9 
10 
11 
12 
13 
14 
15 


Orange 
Brown 

Light Red 
Dark Gray 
Medium Gray 
Light Green 
Light Blue 
Light Gray 


Border Control Memory 53280 
Background Control Memory 53281 


APPENDIX G 


DERIVED TRIGONOMETRIC 
FUNCTIONS 


FUNCTION BASIC EQUIVALENT 






































SECANT SEC(X)=1/COS(X) 

COSECANT CSC(X)=1/SIN(X) 

COTANGENT COT(X)=1/TAN(X) 

INVERSE SINE ARCSIN(X)=ATN(X/SQR(-X*X+1)) 


INVERSE COSINE ARCCOS(X)=-ATN(X/SQR 
(-X*X+1))+ 3/2 
ARCSEC(X)=ATN(X/SQR(X*X-1)) 
ARCCSC(X)=ATN(X/SQR(X*X-1)) 
+(SGN(X)-1 1/2 
ARCOT(XJ=ATN(X)+r/2 
SINH(X)=(EXP(X)-EXP(-X))/2 
COSH(X)=(EXP(X)+EXP(-X))/2 
TANH(X)=EXP(-X/(EXP(X)+EXP 
(-X))*241 
SECH(X)=2/(EXP(X)+EXP(-X)) 
CSCH(X)=2 /(EXP(X)-EXP(-X)) 
COTH(X)=EXP(-X)/(EXP(X) 
-EXP(-X))*2+1 
ARCSINH(X)=LOG(X+SQR(X*X41)) 
ARCCOSH(X)=LOG(X+SQR(X*X-1)) 
ARCTANH(X)=LOG((1+X)/(1-X))/2 
ARCSECH(X)=LOG((SQR 
(-X*X+1)+1/X) 
ARCCSCH(X)=LOG((SGN(X)* SQR 
(X*X+1)/X) 
ARCCOTH(X)=LOG((X+1)/(X-1))/2 












INVERSE SECANT 
INVERSE COSECANT 

















INVERSE COTANGENT 
HYPERBOLIC SINE 

HYPERBOLIC COSINE 
HYPERBOLIC TANGENT 














HYPERBOLIC SECANT 
HYPERBOLIC COSECANT 
HYPERBOLIC COTANGENT 
















INVERSE HYPERBOLIC SINE 
INVERSE HYPERBOLIC COSINE 

INVERSE HYPERBOLIC TANGENT 
INVERSE HYPERBOLIC SECANT 






INVERSE HYPERBOLIC COSECANT 






INVERSE HYPERBOLIC COTANGENT 
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APPENDIX H 


MEMORY MAP 
SYSTEM MEMORY MAP 


The Commodore 128 BASIC memory map is shown below: 


COMMODORE 128 MODE 
MEMORY MAP 


FFFF 
FFFA 
FFDO 


FFOS 


FFOO 


4000 


C128 
RAM 


NMJ RST IRQ 
CP/M RAM Code 
Krnl RAM Code 


FFFF 


FF4D 


FFOS 


MMU 
Configuration Register 





FFOO 


FC80 


BASIC TEXT AREA 
(Basic text begins 
at $1C00 if bit-map 
unallocated) 


FAQO 


E000 


D000 


co00 


8000 


8000 





4000 





C128 
ROM 


SSSSS 44ST 
EA PA A LOA LGM, 
LLP LAS LF LF) 


SBP RD OF PR AT 


Hardware Vectors 


~- ~ Kernal Interrupt 
Dispatch Code 


Registers 


r - - — ROM Reserved tor 
Foreign Lang. Versions 


+ - - - Editor Tables 


L - - - Kernal ROM Code 





- - - - 1/0 Space 





Basic ROM Code 


-=- Kernal Jump Table & - - - - - - - 


[ - - - Editor ROM Code - - - - - - 


L - -- Monitor ROM Cable - - - - 
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4000 


2000 


100 
1800 
1A00 


1800 


1400 
1300 


1200 


1108 


1100 


1000 


OFOO 
0E00 


0000 


0C00 
OBCO 
0800 


OA00 


0900 
0800 


0400 
0380 
033C 
O2FC 
02A2 


0200 
0149 
0110 
0100 
0090 


0002 
0000 


COMMODORE 128 MODE 


MEMORY MAP 


C128 
RAM 


VIC BIT-MAP 
Screen 


VIC BIT-MAP 
Color (Vm #2) 


Reserved for 
Function Key 
Software 





Reserved for 
Foreign Lang 
Systems 


Basic 
Absolute 
Variables 


Basic 
00S/VSP 
Variables 


CP/M Reset 
Code 


Function 
Key 
But fer 


Sprite 
Definition 
Area 
RS-232 


Output 
But fer 


RS-232 


Input 
Bufter 


(Disk Boot Page) 
Cassette Buffer 


Monitor & Kernal 
Absolute 
Variables 


Basic 
Run-Time 
Stack 


Basic RAM Code 


Basic & Monitor 
Input Buffer 





C128 
ROM 
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CONTROL AND ESCAPE CODES 


CONTROL CODES 
Key 
CHR$ Sequence 
CHR$(2) CTRL B 
CHR§(5) CTRL 2 or 
CTALE 
CHR$(7) CTRLG 
CHR§(8) CTRL H 
CHR$(9) CTRL | 
CHR§$(10) CTRL J 
CHR$(11) CTRL K 
CHR§$(12) CTRL L 
CHR$(13) CTRL M 
CHR§$(14) CTRL N 
CHR$(15) CTRL O 
CHRS§(17) CRSR DOWN or 
CTRL Q 
CHR§(18) CTRL 9 


Effective 

in Mode: 

Function C64 C128 
Underline (80) 


Set character color to white 
(40) and (80) 

Produce bell tone 

Disable character set 
change 

Enable character set 
Change 

Move cursor to next set 
tab position 

Send a carriage return 
with line feed. 

Send a line feed 

Disable character set 
change 

Enable character mode 
change 

Send a carriage return and 
line feed to the computer 
and enter a line of BASIC 
Set character set to lower/ 
upper case set 

Turn flash on (80) 

Move the cursor down one 
row 

characters to be 

printed in reverse field 


CHR$ 


CHR$(19) 


CHR$(20) 


CHR$(24) 
CHR$(27) 
CHR$(28) 
CHR$(29) 
CHR$(30) 


CHR$(34) 


CHR§$(129) 


CHR$(130) 
CHR$(131) 


CHR$(133) 
CHR$(134) 
CHR$(135) 


CHR$(136) 


Key 
Sequence 


HOME or 
CTRLS 


DEL or 
CTRL T 


CTRL X 


ESC or CTRL [ 


CTRL 3 or 
CTRL / 
CRSR or 
CTRL ] 
CTRL 6 or 
CTRL 


c 1 


Fq 
F3 
F5 


Fr 


Effective 
in Mode: 


Function C64 C128 


Move the cursor to the 

home position (top left) of 

the display (the current 

window) wr fam 
Delete last character 

typed and move all characters 

to the right of the deleted 

character one space to 


the left a oe 
Tab set/clear 

Send an ESC character * 
Send character color to red 

(40) and (80) x, 
Move cursor one column 

to the right mee, 
Set character color to 

green (40) and (80) me 


Print a double quote 

on screen and place editor 

in quote mode 98, 
Set character color to 

orange (40); dark purple 

(80) * * 
Underline off (80) . 
Run a program. This CHR$ 

code does not work in 

PRINT CHR$ (131), but 

works from keyboard 


buffer me 
Reserved CHR$ code for 
F1 key c F 
Reserved CHR$ code for 
F3 key et 
Reserved CHR$ code for 
F5 key x 
Reserved CHR$ code for 
F7 key <. 


CHR$ 

CHR$(137) 
CHR$(138) 
CHR$(139) 
CHR§(1 40) 


CHR$(141) 


CHR$(142) 


CHR$(143) 
CHR$(144) 


CHR$(145) 
CHR$(146) 


CHR$(147) 


CHR$(148) 
CHR$(149) 
CHR$(150) 


CHR$(151) 


CHR$(152) 
CHR$(153) 


CHR$(154) 


Key 
Sequence 


F2 
F4 
F6 
F8 


SHIFT RETURN 


CTRL 1 
CRSR UP 
CTRL 0 


HOME 


INST 
« 2 
C 3 
4 


& 5 
c 6 
7 


Effective 
in Mode: 


Function 


Reserved CHR$ code for 
F2 key 

Reserved CHR$ code for 
F4 key 

Reserved CHR$ code for 
F6 key 

Reserved CHR$ code for 
F8 key 

Send a carriage return and 
line feed without entering 

a BASIC line 

Set the character set to 
upper case graphic 

Turn flash off (80) 

Set character color to 
black (40) and (80) 

Move cursor or printing 
position up one row 
Terminate reverse field 
display 

Clear the window screen 
and move the cursor to the 
top left position 

Move character from cur- 
sor position right one column 
Set character color to 
brown (40); dark yellow (80) 
Set character color to 

light red (40) and (80) 

Set character color to 

dark grey(40)and dark cyan 
(80) 

Set character color to 
medium grey (40) and (80) 
Set character color to 

light green(40)and(80) 

Set character color to 

light blue(40)and(80) 


C64 C128 


Effective 


Key in Mode: 

CHR$ Sequence Function C64 C128 
CHR$(155)  & 8 Set character color to 

light grey(40)and(80) aes 
CHR$(156) CTRL5 Set character color to purple 

(40)and(80) wR 
CHR$(157) CRSRLEFT Move cursor left by one 

column Pe oe 
CHR$(158) CTRL4 Set character color to cyan 

(40); light cyan (80) _ 


NOTE: (40) ... 40 column screen only 
(80) ... 80 column screen only 


ESCAPE CODES 


Following are key sequence for the ESCape functions available on the 
Commodore 128. ESCape sequences are entered by pressing and 
releasing the “ESC” key, followed by pressing the key listed below. 


ESCAPE FUNCTION 


ESCAPE KEY 

Cancel quote and insert mode ESC O 
Erase to end of current line ESCQ 
Erase to start of current line ESCP 

Clear to end of screen ESC @ 
Move to start of current line ESC J 

Move to end of current line ESC K 
Enable auto-insert mode ESCA 
Disable auto-insert mode ESC C 
Delete current line ESC D 
Insert line ESC | 

Set default tab stop (8 spaces) ESC Y 
Clear all tab stops FSC Z 
Enable scrolling ESC L 

Disable scrolling ESC M 


Scroll up ESC V 


Scroll down ESC W 
Enable bell (by control-G) ESC G 
Disable bell ESCH 
Set cursor to non-flashing mode ESCE 
Set cursor to flashing mode ESC F 
Set Bottom of screen window at cursor position ESC B 
Set top of screen window at cursor position ESC T 
Swap 40/80 column display output device ESC X 


The following ESCape sequences are valid on an 80-column screen only 
(See Section 8 for information on using an 80-column screen.) 


Change to underlined cursor ESC U 
Change to block cursor ESCS 
Set screen to reverse video ESC R 
Return screen to normal (non reverse video) state ESC N 


NOTE: (40)...40 column screen only 
(80)...80 column screen only 


APPENDIX J 


MACHINE LANGUAGE 
MONITOR 


INTRODUCTION 


Commodore 128 has a built-in machine language monitor which 
lets the user write and examine machine language programs 
easily. Commodore 128 MONITOR includes a machine language 
monitor, a mini-assembler and a disassembler. The built-in 
monitor works only in C128 mode; either 40 column or 80 
column. 


Machine language programs written using Commodore 128 
MONITOR can run by themselves or be used as very fast 
subroutines for BASIC programs since the Commodore 128 
MONITOR has the ability to coexist peacefully with BASIC. 


Care must be taken to position the assembly language programs 
in memory so the BASIC program does not overwrite them. 


To enter the monitor from BASIC, type: 
MONITOR —=REFuRRE 


Summary of Commodore 128 Monitor Commands 
ASSEMBLE Assembles a line of 8502 code 


COMPARE Compares two sections of memory and 
reports differences 


DISASSEMBLE Disassembles a line of 8502 code 


Pik: Fills a range of memory with the specified 
byte 

GO Starts execution at the specified address 

HUNT Hunts through memory within a specified 
range for all occurrances of a set of 
bytes 

JUMP Jumps to the subroutine 


LOAD Loads a file from tape or disk 


MEMORY Displays the hexadecimal values of memory 
locations 

REGISTERS Displays the 8502 registers 

SAVE Saves to tape or disk 

TRANSFER Transfers code from one section of memory 
to another 

VERIFY Compares memory with tape or disk 

EXIT Exits Commodore 128 MONITOR 

(period) Assembles a line of 8502 code 

(greater than) Modifies memory 

(semicolon) Modifies 8502 register displays 

(at sign) Displays disk status, sends disk command, 


displays directory 


The commodore 128 displays 5-digit hexadecimal addresses 
within the machine language monitor. Normally, a hexadecimal 
number is only four digits, representing the allowable address 
range. The extra left-most (high order) digit specifies the BANK 
configuration (at the time the given command is executed) 
according to the following memory configuration table: 


0-RAM 0 only 8-EXT ROM, RAM 0,1/0 

1-RAM 1 only 9-EXT ROM, RAM 1,1/0 

2-RAM 2 only A-EXT ROM, RAM 2,1/0 

3-RAM 3 only B-EXT ROM, RAM 3,1/0 

4-INT ROM, RAM 0,1/0 C-KERNAL + INT (io), RAM 0,1/0 

5-INT ROM, RAM 1,1/0 D-KERNAL + EXT (lo), RAM 0,1/0 

6-INT ROM, RAM 2,1/0 E-KERNAL + BASIC, RAM 0, CHARROM 
7-INT ROM, RAM 3,1/0 F-KERNAL + BASIC, RAM 0, 1/0 


Summary of Monitor Field Descriptors 


The following designators precede monitor data fields 
(e.g.,memory dumps). When encountered as a command, these 
designators instruct the monitor to alter memroy or register 
contents using the given data. 
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. <period> precedes lines of disassembled code. 
> <right angle> precedes lines of memory dump. 
; <semicolon> precedes line of a register dump. 


The following designators precede number fields (e.g.,address) 
and specify the radix (number base) of the value. Entered as 
commands, these designators instruct the monitor simply to 
display the given value in each of the four radices. 


<null> (default) precedes hexidecimal values. 
$ <dollar> precedes hexidecimal (base-16) values. 
+ <plus> precedes decimal (base-10) values. 
& <ampersand> precedes octal (base-8) values. 
% <percent> precedes binary (base-2) values. 


The following characters are used by the monitor as field 
delimiters or line terminator (unless encountered within an ASCII 
string). 


<space> delimiterseparates two fields. 

» <comma> delimiterseparates two fields. 
<colon> terminatorlogical end of line. 

? <question> terminatorlogical end of line. 


Note: < > enclose required parameters 
[ ] enclose optional parameters 


COMMODORE 128 MONITOR COMMAND 
DESCRIPTIONS 


Please note that nay number field (e.g.,addresses, device 
number, and data bytes) may be specified as a based number. 
This affects the operand field of the ASSEMBLE command as 
well. Also note the addition of the directory syntax to the disk 
command. 


As a further aid to programmers, the Kernal error message facility 
has been automatically enabled while in the Monitor. This means 
the Kernal will display “I/O ERROR#” and the error code, should 
there be any failed |/O attempt from the MONITOR. The 
message facility is turned off when exiting the MONITOR. 
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COMMAND: A 
PURPOSE: Enter a line of assembly code. 
SYNTAX: A <address> <opcode mnemonic> <operand> 


<address> A hexadecimal number 
indicating the location in memory 
to place the opcode. 


<opcode 

mnemonic> A standard MOS technology 
assembly language mnemonic, 
e.g., LDA, STX, ROR. 


<operand> The operand, when required, can 
be any of the legal addressing 
modes. 
A RETURN is used to indicate the end of the assembly line. If 
there are any errors on the line, a question mark is displayed to 
indicate an error, and the cursor moves to the next line. The 
screen editor can be used to correct the error(s) on that line. 


EXAMPLE 


.A01200 LDX #$00 
A 1202 


NOTE: A period (.) is equal to the ASSEMBLE command. 
EXAMPLE: 
02000 LDA #$23 


COMMAND: C 
PURPOSE: Compare two areas of memory. 
SYNTAX: C <address 1> <address 2> <address 3> 


<address 1> A number indicating the start 
address of the area of memory to 
compare against. 

<address 2> A hexadecimal number 
indicating the end address of the 
area of memory to compare 
against. 

<address 3> A number indicating the start 
address of the other area of 
memory to compare with. 


Addresses that do not agree are printed on the screen. 
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COMMAND: D 

PURPOSE: Disassemble machine code into assembly 
language 
mnemonics and operands. 

SYNTAX: D [<address1>][<address 2>] 


<addressi> Anumber setting the address to 


start the disassembly. 


<address 2> An optional ending address of 
code to be disassembled. 


The format of the disassembly differs slightly from the input 


format of an assembly. The difference is that the first character of 


a disassembly is a period rather than an A (for readability), and 
the hexidecimal of the code is listed as well. 


A disassembly listing can be modified using the screen editor. 


Make any changes to the mnemonic or operand on the screen, 


then hit the carriage return. This enters the line and calls the 
assembler for further modifications. 


A disassembly can be paged. Typing a D <<RETURN> causes 
the next page of disassembly to be displayed. 


EXAMPLE: 
D 3000 3003 
03000 A900 LDA #$00 
03002 FF feats 
.03003 DO 2B BNE $3030 
COMMAND: F 


PURPOSE: Fill a range of locations with a specified byte. 
SYNTAX: F <address 1><address 2> <byte> 


<address 1> The first location to fill with the 
<byte>. 


<address 2> The last location to fill with the 
<byte>. 


<byte value> Number to be written. 


This command is useful for initializing data structures or any 
other RAM area. 
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EXAMPLE: 
F 0400 0518 EA 


Fill memory locations from $0400 to $0518 with 
$EA (a NOP instruction). 


COMMAND: G 
PURPOSE: Begin execution of a program at a specified 
address. 


SYNTAX: G [<address>] 


<address> An address where execution Is to 
start. When address is left out, 
execution begins at the current 
PC. (The current PC can be 
viewed using the R command.) 


The GO command restores all registers (displayable by using the 
R command) and begins execution at the specified starting 
address. Caution is recommended in using the GO command. To 
return to Commodore 128 MONITOR mode after executing a 
machine language program, use the BRK instruction at the end of 
the program. 


EXAMPLE: 
G140C 
Execution begins at location $140C. 
COMMAND: H 
PURPOSE: Hunt through memory within a specified range for 


all occurrences of a set of bytes. 
SYNTAX: H <address 1><address 2> <data> 


<address 1> Beginning address of hunt 


procedure. 

<address 2> Ending address of hunt 
procedure. 

<data> Data set to search for data may 


be numbers or an ASCII string. 


EXAMPLE: 
H A000 A101 AQ FF 4C 
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Search for data $A9, $FF, $4C, 
from AOOO to A101. 


H 2000 9800 'CASH 
Search for the alpha string “CASH”. 
COMMAND: L 


PURPOSE: Load a file from cassette or disk. 
SYNTAX: L <‘file name'>[<device> [,alt load address]] 


<‘‘file name'> Any legal Commodore 128 
file name. 
<device> A hexadecimal number 


indicating the device to load 
from. 1 is cassette. 
8 is disk (or 9, A, etc.) 

[alt load address] Option to load a file toa 
specified address. 


The LOAD command causes a file to be loaded into memory. If 
the alternate load address is not used, the file will be loaded to 
the address in bank 0 that is specified in the cassette header, or 
the first two bytes of a disk file. The alternate load address is 
used to specify a different start address, which may range from 
$00000 to $FFFFF. 


EXAMPLE: 
L “PROGRAM”, $12000 


Loads the file named PROGRAM in from the disk in to bank 1 
starting at $2000. 


COMMAND: M 

PURPOSE: To display memory as a hexadecimal and ASCII 
dump within the specified address range. 

SYNTAX: M [<address 1>] (<address2>] 


<address 1>] First address of memory dump. 
Optional. If omitted, one page is 
displayed. The first byte is the 
bank number to be displayed, the 
next four bytes are the first 
address to be displayed. 
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<address 2>] Last address of memory dump. 
Optional. If omitted, one page is 
displayed. The first byte is the 
bank number to be dis-played, 
the next four bytes are the 
ending address to be displayed. 


Memory is displayed in the following format: 
>03000 45 58 2E 56 41 4C 55 45:EX. VALUE 


Memory content may be edited using the screen editor. Move the 
cursor to the data to be modified, type the desired correction and 
hit RETURN. If there is a bad RAM location or an attempt to 
modify ROM has occurred, an error flag (?) is displayed. An 
ASCII dump of the data is displayed in REVERSE (to contrast with 
other data displayed on the screen) to the right of the hex data. 
When a character is not printable, it is displayed as a reverse 
period (.). As with the disassembly commana, paging down is 
accomplished by typing M and RETURN. 


EXAMPLE: 


M F41F1 F4201 


>F41F1 20 43 4F 4D 4D 4F 44 4F: COMMODO 
>F41F9 52 45 20 45 4C 45 43 54:RE ELECT 
>F4201 52 4F 4E 49 43 53 2C 20:RONICS, 


Note: The above display is produced by the 40-column editor. 


COMMAND: R 

PURPOSE: Show important 8502 registers. The program status 
register, the program counter, the accumulator, the 
X and Y index registers and the stack pointer are 


displayed. 
SYNTAX: R 
EXAMPLE: 
R 


PC SR AC XR YR_ SP 
,01 002 01 02 O03 04 FE 


NOTE: ; (semicolon) can be used to modify register 
displays in the same fashion as > can be used 
to modify memory registers. 
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COMMAND: § 

PURPOSE: Save an area of memory onto tape or disk. 

SYNTAX: S <"file name’><device>,<address 1>, 
<address 2> 


<‘‘file name’’> Any legal Commodore 128 file 
name. To save the data the file 
name must be enclosed in 
double quotes. Single quotes 
Cannot be used. 

<device> A number indicating on which 
device the file is to be placed. 
Cassette is 1; disk is 8, 9,etc. 

<address 1> Starting address of memory to be 
saved, 

<address 2> Ending address of memory to be 
saved + 1. All data up to, but not 
including the byte of data at this 
address, is Saved. 


The file may be recalled, using the L command. When saving to 
cassette only bank 0 can be saved from. 


EXAMPLE: 
S “GAME” 8,0400,0C00 
Saves memory from $0400 to $0C00 onto disk. 


COMMAND: T 

PURPOSE: Transfer segments of memory from one memory 
area to another. 

SYNTAX: T <address 1><address 2> <address 3> 


<address 1> Starting address of data to be 
moved. 

<address 2> Ending address of data to be 
moved. 

<address 3> Starting address of new location 
where data will be moved. 
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Data can be moved from low memory to high memory and vice 
versa. Additional memory segments of any length can be moved 
forward or backward. An automatic “compare” is performed as 
each byte is transferred, and any differences are listed by 
address. 


EXAMPLE: 
T 1400 1600 1401 


Shifts data from $1400 up to and including $1600 
one byte higher in memory. 


COMMAND: V 
PURPOSE: Verify a file on cassette or disk with the memory 
contents. 


SYNTAX: V <‘file name'’>[,<device>] [,alt start address] 


<‘‘file name’’>Any legal Commodore 128 file 
name. 

<device> A number indicating which 
device the file is on; cassette is 


1, disk is 8, 

9, etc. 
[alt start Option to start verification at this 
address] address. 


The verify command compares a file to memory contents. The 
Commodore 128 responds with VERIFYING. If an error is found 
the word ERROR is added; if the file is successfully verified the 
Cursor reappears. 


EXAMPLE: 
V “WORKLOAD”, 8 


COMMAND: X 
PURPOSE: Exit to BASIC. 
SYNTAX: X 


COMMAND: > (greater than) 
PURPOSE: Can be used to set up to 8 or 16 locations. 
SYNTAX: > <address>[<data byte 1 ....8/16>] 
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<address> First memory address to set. 
<data byte 1...8/16> 
Data to be placed in the succes- 
sive memory locations following 
the address with a space 
preceding each data byte. 


The maximum number of bytes that can be entered is 8 (in 40 
column mode) or 16 (in 80 column mode). When the RETURN 
key is pressed the contents of the 8/16 locations after the 
address are displayed 

EXAMPLES: 


>2000 
displays line of bytes following $2000 


>2000 31 32 38 
enters values at $2000 and displays line of bytes following $2000 


COMMAND: @ (at sign) 
PURPOSE: Can be used to display the disk status. 
SYNTAX: @ [<unit#>], <<disk cmd string> 


<unit #> Device unit number (optional). 
<disk cmd string> 
String command to disk. 

NOTE: @ alone gives the status of the disk drive. 
EXAMPLES: 
@ 
00, OK, 00, 00 
Checks disk status 
initializes drive 8 


@$ 


displays directory of drive 8 
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APPENDIX K 
BASIC 7.0 ABBREVIATIONS 


Note: The abbreviations below operate in uppercase/ graphic 


mode. Press the letter key(s) indicated, then hold down the 


SHIFT key and press the letter key following the word 
SHIFT. 


KEYWORD 


ABS 
APPEND 
ASC 

ATN 
AUTO 
BACKUP 
BANK 
BEGIN 
BEND 
BLOAD 
BOOT 
BOX 
BSAVE 
BUMP 
CATALOG 
CHAR 
CHR$ 
CIRCLE 
CLOSE 
CLR 
CMD 
COLLECT 
COLINT 
COLLISION 
COLOR 
CONCAT 
CONT 
COPY 
COS 


ABBREVIATION 


A SHIFT B 

A SHIFT P 

A SHIFT S 

A SHIFT T 

A SHIFT U 

BA SHIFT C 

B SHIFT A 

B SHIFT E 

BE SHIFT N 

B SHIFT L 

B SHIFT O 
none 

B SHIFTS 

B SHIFT U 

C SHIFT A 

CH SHIFT A 

C SHIFT H 

C SHIFT | 

CL SHIFT O 

C SHIFT L 

C SHIFT M 

COLL SHIFT E 
none 

COL SHIFT L 

COL SHIFT O 

C SHIFT O 
none 

CO SHIFT P 
none 
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KEYWORD 


DATA 
DEC 
DCLEAR 
DCLOSE 
DEF FN 
DELETE 
DIM 
DIRECTORY 
DLOAD 
DO 
DOPEN 
DRAW 
DSAVE 
DVERIFY 
EL 

END 
ENVELOPE 


FILTER 
FOR 

FRE 
FNxx 
GET. 
GETKEY 
GET# 
GOSUB 
GO64 
GOTO 
GRAPHIC 
GSHAPE 
HEADER 
HELP 
HEX$ 
[FzGOTO 
IF... THEN...ELSE 
INPUT 
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ABBREVIATION 


D SHIFT A 
none 
DCL SHIFT E 
D SHIFT C 
none 
DE SHIFT L 
D SHIFT | 
DI SHIFT R 
D SHIFT L 
none 
D SHIFT O 
D SHIFT R 
D SHIFT S 
D SHIFT V 
none 
none 
E SHIFT N 
none 
E SHIFT R 
EX SHIFT | 
E SHIFT X 
none 
POSRIETE 
F SHIFT | 
F SHIFT O 
F SHIFT R 
none 
G SHIFT E 
GETK SHIFT E 
none 
GO SHIFT S 
none 
GSHlFTO 
G SHIFT R 
G SHIFT S 
HE SHIFT A 
HE SHIFT L 
ASHIFA iE 
none 
none 
none 


KEYWORD 


INPUT# 
INSTR 
INT 

JOY 

KEY 
LEFTD 
LEN 

Ley 

LIST 
LOAD 
LOCATE 
LOG 
LOOP 
MID$ 
MONITOR 
MOVESHAPE 
MOVSPR 
NEW 
NEXT 
ON...GOSUB 
ON...GOTO 
OPEN 
PAINT 
PEEK 
PEN 

P| 

PLAY 
POKE 
POS 

POT 
PRINT 
PRINT# 
PRINT USING 
PUDEF 
RBUMP 
RCLR 
RDOT 
READ 
RECORD 
REM 
RENAME 


ABBREVIATION 


| SHIFT N 
IN SHIFT S 
none 
J SHIFT O 
K SHIFT E 
LE-SHIETF 
none 
L SHIFT E 
L SHIFT | 
L SHIFT O 
LO SHIFT C 
none 
LO SHIFT O 
M SHIFT | 
MO SHIFT N 
none 
M SHIFT O 
none 
N SHIFT E 

ON...GO SHIFT S 
ON...G SHIFT O 
O SHIFT P 
P SHIFT A 
PE SHIFT E 
P SHIFT E 
none 
P SHIFT L 
PO SHIFT O 
none 
P SHIFT O 
? 
P SHIFT R 
?US SHIFT | 
P SHIFT U 
RB SHIFT U 
R SHIFT C 
R SHIFT D 
RE SHIFT A 
R SHIFT E 
none 
RE SHIFT N 
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KEYWORD 


RENUMBER 
RESTORE 
RESUME 
RETURN 
RGR 
RIGHT$ 
RLUM 
RND 
RREG 
RSPCOLOR 
RSPPOS 
RSPR 
RSPRITE 
RUN 
RWINDOW 
SAVE 
SCALE 
SCNCLR 
SCRATCH 
SGN 

SIN 
SLEEP 
SLOW 
SOUND 
SPC( 
SPRCOLOR 
SPRDEF 
SPRITE 
SPRSAV 
SQR 
SSHAPE 
STASH 
STatus 
STEP 
STOP 
STR$ 
SWAP 
SYS 
TAB( 
TAN 
TEMPO 
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ABBREVIATION 


REN SHIFT U 

RE SHIFT S 

RES SHIFT U 

RE SHIFT T 

R SHIFT G 
R SHIFT 
none 

R SHIFT N 

R SHIFT R 

RSP'SHIFET C 

R SHIFT S 
none 

RSP SHIFT R 

R SHIFT U 

R SHIFTW 

S SHIFT A 

SC SHIFT A 

S SHIFT C 

SC SHIFT R 

S SHIFT G 

S SHIFT | 

S SHIFT L 
none 

S SHIFT O 
none 

SPR SHIFT C 

SPR SHIFT D 

S SHIFT P 

SPR SHIFT S$ 

S SHIFT Q 

S SHIFT S 

S SHIFT T 
none 

ST SHIFT E 

ST SHIFT O 

ST SHIFT R 

S SHIFTW 
none 

T SHIFT A 
none 

T SHIFT E 


KEYWORD ABBREVIATION 


Tl none 

TI$ none 

TO none 

TRAP T SHIFT R 
TROFF TRO SHIFT F 
TRON TR SHIFT O 
UNTIL U SHIFT N 
USR SHIFTS 
VAL none 

VERIFY V SHIFT E 
VOL V SHIFT O 
WAIT W SHIFT A 
WHILE W SHIFT H 
WIDTH WI SHIFT D 
WINDOW W SHIFT | 


XOR X SHIFT O 


APPENDIX L 
DISK COMMAND SUMMARY 


This appendix lists the commands used for disk operation in 
C128 and C64 modes on the Commodore 128. For detailed 
information on any of these commands, see Chapter V, BASIC 
7.0 Encyclopedia. Your disk drive manual also has information on 
disk commands. 


The new BASIC 7.0 commands can be used only in C128 mode. 
All BASIC 2.0 commands can be used in both C128 and C64 
modes. 


Command Use Basic 2.0 Basic 7.0 
APPEND Append data to file * JV 
BLOAD Load a binary file J 


Starting at the 
specified memory 


location 

BOOT Load and execute JV 
program 

BSAVE Save a binary file JV 


from the specified 
memory location 





CATALOG Display directory J 
contents of disk on 
screen * 

CLOSE Close logical disk J J 
file 

CMD Redirect screen output JV JV 
to disk file 

COLLECT Free inaccessible JV 
disk space * 

CONCAT Concatenates two JV 
data files * 


* Although there is no single equivalent command in BASIC 2.0, there 
is an equivalent multi-command instructions. See your disk drive 
manual for these BASIC 2.0 conventions. 
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Command 
COPY 


DCLEAR 


DCLOSE 


DIRECTORY 


DLOAD 


DOPEN 


DSAVE 
DVERIFY 
GET# 
HEADER 
LOAD 
OPEN 


PRINT# 
RECORD 


RENAME 


RUN filename 


SAVE 


VERIFY 


Use 


Copy files between 
drives * 

Resets and initialises 
disk drives * 


Close logical disk 

files 

Display directory of 
contents of disk on 
screen * 

Load a BASIC program 
from disk * 

Open a disk file for 

a read and/or write 
operation * 

Save a BASIC program 
to disk * 

Verify program in memory 


against programs on disk * 


Recieve input from open 
disk file 

Format a disk * 

Load a file from disk 
Open a file for input 

or Output 

Output data to file 
Position relative file 
pointers * 

Change name of a file 
on disk * 

Execute BASIC program 
from disk 

Store program in memory 
to disk 

Verify program in 
memory against program 
on disk 


Basic 2.0 


Basic 7.0 
J 


J 


es 


_ 


* Although there is no single equivalent command in BASIC 2.0, there 
is an equivalent multi-command instruction. See your disk drive 


manual for these BASIC 2.0 conventions. 
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GLOSSARY 


This glossary provides brief definitions of frequently used 
computing terms. 


Acoustic Coupler or Acoustic Modem: A cevice that converts 
digital signals to audible tones for transmission over 
telephone lines. Speed is limited to about 1,200 baud, or bits 
per second (bps). Compare direct-connect modem. 


Address: The label or number identifying the register or memory 
location where a unit of information is stored. 


Alphanumeric: Letters, numbers and special symbols found on the 
keyboard, excluding graphic characters. 


ALU: Arithmetic Logic Unit. The part of a Central Processing Unit 
(CPU) where binary data is acted upon. 


Animation: The use of computer instructions to simulate motion of 
an object on the screen through gradual, progressive 
movements. 


Array: A data-storage structure in which a series of related 
constants or variables are stored in consecutive memory 
locations. Each constant or variable contained in an array is 
referred to as anelement. An element is accessed using a 
subscript. See Subscript. 


ASCII: Acronym for American Standard Code for Information 
Interchange. A seven-bit code used to represent 
alphanumeric characters. It is useful for such things as 
sending information from a keyboard to the computer, and 
from one computer to another. See Character String Code. 


Assembler: A program that translates assembly-language 
instructions into machine-language instructions. 


GL-1 


Assembly Language: A machine-oriented language in which 
mnemonics are used to represent each machine-language 
instruction. Each CPU has its own specific assembly 
language. See CPU and machine language. 


Assignment Statement: A BASIC statement that sets a variable, 
constant or array element to a specific numeric or string 
value. 


Asynchronous Transmission: A scheme in which data characters 
are sent at random time intervals. Limits phone-line 
transmission to about 2,400 baud (bps). See Synchronous 
Transmission. 


Attack: The rate at which the volume of a musical note rises from 
zero to peak volume. 


Background Color: The color of the portion of the screen that the 
Characters are placed upon. 


BASIC: Acronym for Beginner's All-purpose Symbolic Instruction 
Code. 


Baud: Serial-data transmission speed. Originally a telegraph term, 
300 baud Is approximately equal to a transmission speed of 
30 bytes or characters per second. 


Binary: A base-2 number system. All numbers are represented as 
a sequence of zeros and ones. 


Bit: The abbreviation for Binary digIT. A bit is the smallest unit in 
a computer. Each binary digit can have one of two values, 
zero or one. A bit is referred to as enabled or “on” if it equals 
one. A bit is disabled or “off” if it equals zero. 


Bit Control: A means of transmitting serial data in which each bit 
has a significant meaning and a single character is 
surrounded with start and stop bits. 

Bit Map Mode: An advanced graphic mode in the Commodore 
128 in which you can control uvery dot on the screen. 
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Border Color: The color of the edges around the screen. 


Branch: To jump to a section of a program and execute it. GOTO 
and GOSUB are examples of BASIC branch instructions. 


Bubble Memory: A relatively new type of computer memory, it 
uses tiny magnetic “pockets” or “bubbles” to store data. 


Burst Mode: A special high speed mode of communication 
between a disk drive and a computer, in which information is 
transmitted at many times normal speed. 


Bus: Parallel or serial lines used to transfer signals between 
devices. Computers are often described by their bus structure 
(i.e., S-100-bus computers, etc.). 


Bus Network: A system in which all stations or computer devices 
communicate by using a common distribution channel or bus. 


Byte: A group of eight bits that make up the smallest unit of 
addressable storage in a computer. Each memory location in 
the Commodore 128 contains one byte of information. One 
byte is the unit of storage needed to represent one character 
in memory. See Bit. 


Carrier Frequency: A constant signal transmitted between 
communicating devices that is modulated to encode binary 
information. 


Character: Any symbol on the computer keyboard that is printed 
onthe screen. Characters include numbers, letters, 
punctuation and graphic symbols. 


Character Memory: The area in Commodore 128’s memory which 
stores the encoded character patterns that are displayed on 
the screen. 


Character Set: A group of related characters. The Commodore 
128 character sets consist of: upper-case letters, lower-case 
letters and graphic characters. 
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Character String Code: The numeric value assigned to represent 
a Commodore 128 character in the computer's memory. 


Chip: A miniature electronic circuit that performs a computer 
operation such as graphics, sound and input/output. 


Clock: The timing circuit for a microprocessor. 
Clocking: A technique used to synchronize a sending and a 
receiving data-communications device that is modulated to 


encode binary information. 


Collision Detection: The recognition of the collision of sprites with 
other sprites or display data. 


Color Memory: The area in the Commodore 128's memory that 
controls the color of each location in screen memory. 


Command: A BASIC instruction used in direct mode to perform an 
action. See Direct Mode. 


Compiler: A program that translates a high-level language, such 
as BASIC, into machine language. 


Composite Monitor: A device used to provide a 40-column video 
display. 


Computer: An electronic, digital device that stores and processes 
information. 


Condition: Expression(s) between the words IF and THEN, 
evaluated as either true or false inan IF... THEN statement. 
The condition IF... THEN statement gives the computer the 
ability to make decisions. 


Coordinate: A single point on a grid having vertical (Y) and 
horizontal (X) values. 


Counter: A variable used to keep track of the number of times an 
event has occurred in a program. 


CPU: Acronym for Central Processing Unit. The part of the 


GL-4 


computer containing the circuits that control and perform the 
execution of computer instructions. 


Crunch: To minimize the amount of computer memory used to 
store a program. 


Cursor: The flashing square that marks the current location on the 
screen. 


Data: Numbers, letters or symbols that are input into the computer 
to be processed. 


Data Base: A large amount of data stored in a well-organized 
manner. A data-base management system is a program that 
allows access to the information. 


Data Link Layer: A logical portion of data communications control 
that mainly ensures that communication between adjacent 
devices is error free. 


Data Packet: A means of transmitting serial data in an efficient 
package that includes an error-checking sequence. 


Data Rate or Data Transfer Rate: The speed at which data Is sent 
to a receiving computer—given in baud, or bits per second 
(bps). 


Datassette: A device used to store programs and data files 
sequentially on tape. 


Debug: To correct errors in a program. 


Decay: The rate at which the volume of a musical note decreases 
from its peak value to a mid-range volume called the sustain 
level. See Sustain. 


Decrement: To decrease an index variable or counter by a 
specific value. 


Dedicated Line or Leased Line: A special telephone line 
arrangement supplied by the telephone company, and 
required by certain computers or terminals, whereby the 
connection is always established (an exclusive, rented line). 
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Delay Loop: An empty FOR... NEXT loop that slows the 
execution of a program. 


Dial-Up Line: The normal switched telephone line that can be 
used as a transmission medium for data communications. 


Digital: Of or relating to the technology of computers and data 
communications where all information is encoded as bits of 
1s or Os that represent on or off states. 


Dimension: The property of an array that specifies the direction 
along an axis in which the array elements are stored. For 
example, a two-dimensional array has an X-axis for columns 
and a Y-axis for rows. See Array. 


Direct Mode: The mode of operation that executes BASIC 
commands immediately after the RETURN key is pressed. 
Also called Immediate Mode. See Command. 

Direct Connect Modem: A digital non-acoustic modem. 


Disable: To turn off a bit, byte or specific operation of the 
computer. 


Disk Drive: A random access, mass-storage device that saves 
and loads files to and from a floppy diskette. 


Disk Operating System: Program used to transfer information to 
and from a disk. Often referred to as a DOS. 


Duration: The length of time a musical note is played. 
Electronic Mail or E-Mail: A communications service for computer 
users where textual messages are sent to a central computer, 


or electronic “mail box,” and later retrieved by the addressee. 


Enable: To turn on a bit, byte or specific operation of the 
computer. 


Envelope Generator: Portion of the Commodore 128 that 


produces specific envelopes (attack, decay, sustain, release) 
for musical notes. See Waveform. 
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EPROM: A PROM that can be erased by the user, usually by 
exposing it to ultraviolet lignt. See PROM. 


Error Checking or Error Detection: Software routines that identify, 
and often correct, erroneous data. 


Execute: To perform the specified instructions in a command or 
program statement. 


Expression: A combination of constants, variables or array 
elements acted upon by logical, mathematical or relational 
operators that return a numeric value. 


File: A program or collection of data treated as a unit and stored 
on disk or tape. 


Firmware: Computer instructions stored in ROM, as ina game 
Cartridge. 


Frequency: [he number of sound waves per second of a tone. 
The frequency corresponds to the pitch of the audible tone. 


Full-Duplex Mode: Allows two computers on the same line to 
transmit and receive data at the same time. 


Function: A predefined operation that returns a single value. 


Function Keys: The four keys on the far right of the Commodore 
128 keyboard. Each key can be programmed to execute a 
series of instructions. Since the keys can be SHIFTed, you 
can create eight different sets of instructions. 


Graphics: Visual screen images representing computer data in 
memory (i.e., characters, symbols and pictures). 


Graphic Characters: Non-alphanumeric characters on the 
computer's keyboard. 


Grid: A two-dimensional matrix divided into rows and columns. 


Grids are used to design sprites and programmable 
characters. 
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Half-Duplex Mode: Allows transmission in only one direction at a 
time; if one device is sending, the other must simply receive 
data until it's time for it to transmit. 


Hardware: Physical components in a computer system such as 
keyboard, disk drive and printer. 


Hexadecimal: Refers to the base-16 number system. Machine 
language programs are often written in hexadecimal notation. 


Home: The upper-left corner of the screen. 


IC: Integrated Circuit. A silicon chip containing an electric circuit 
made up of components such as transistors, diodes, resistors 
and capacitors. Integrated circuits are smaller, faster and 
more efficient than the individual circuits used in older 
computers. 


Increment: To increase an index variable or counter with a 
specified value. 


Index: The variable counter within a FOR... NEXT loop. 


Input: Data fed into the computer to be processed. Input sources 
include the keyboard, disk drive, Datassette or modem. 


Integer: A whole number (i.e., a number containing no fractional 
part), such as 0, 1, 2, etc. 


Interface: The point of meeting between a computer and an 
external entity, whether an operator, a peripheral device or a 
communications medium. An interface may be physical, 
involving a connector, or logical, involving software. 


I/O: Input/output. Refers to the process of entering data into the 
computer, or transferring data from the computer to a disk 
drive, printer or storage medium. 


Keyboard: input component of a computer system. 


Kilobyte (K): 1,024 bytes. 


Local Network: One of several short-distance data 
communications schemes typified by common use of a 
transmission medium by many devices and high-data speeds. 
Also called a Local Area Network, or LAN. 


Loop: A program segment executed repetitively a specified 
number of times. 


Machine Language: The lowest level language the computer 
understands. The computer converts all high-level languages, 
such as BASIC, into machine language before executing any 
statements. Machine language is written in binary form that a 
computer can execute directly. Also called machine code or 
object code. 


Matrix: A two-dimensional rectangle with row and column values. 


Memory: Storage locations inside the computer. ROM and RAM 
are two different types of memory. 


Memory Location: A specific storage address in the computer. 
There are 131,072 memory locations (0-131,071) in the 
Commodore 128. 


Microprocessor: A CPU that is contained on a single integrated 
circuit (IC). Microprocessors used in Commodore personal 
computers include the 6510, the 8502 and the Z80. 


Mode: A state of operation. 


Modem: Acronym for MOdulator/DEModulator. A device that 
transforms digital signals from the computer into electrical 
impulses for transmission over telephone lines, and does the 
reverse for reception. 


Monitor: A display device resembling a television set but with a 
higher-resolution (sharper) image on the video screen. 


Motherboard: [n a bus-oriented system, the board that contains 


the bus lines and edge connectors to accommodate the other 
boards in the system. 
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Multi-Color Character Mode: A graphic mode that allows you to 
display four different colors within an 8 X 8 character grid. 


Multi-Color Bit Map Mode: A graphic mode that allows you to 
display one of four colors for each pixel within an 8 x 8 
character grid. See Pixel. 


Multiple-Access Network: A flexible system by which every 
Station can have access to the network at all times; provisions 
are made for times when two computers decide to transmit at 
the same time. 


Null String: An empty character ("”). A character that is not yet 
assigned a character string code. 


Octave: One full series of eight notes on the musical scale. 


Operating System: A built-in program that controls everything your 
computer does. 


Operator: A symbol that tells the computer to perform a 
mathematical, logical or relational operation on the specified 
variables, constants or array elements in the expression. 
The mathematical operators are +,-,*,/ and t. The 
relational operators are <<, =, >,< =,>=and< >. The 
logical operators are AND, OR, NOT, and XOR. 


Order of Operations: Sequence in which computations are 
performed in a mathematical expression. Also called 
Heirarchy of Operations. 


Parallel Port: A port used for simultaneous transmission of data 
one byte at a time over multiple wires, one bit per wire. 


Parity Bit: A 1 or 0 added to a group of bits that identifies the sum 
of the bits as odd or even. 


Peripheral: Any accessory device attached to the computer such 
as a disk drive, printer, modem or joystick. 


Pitch: The pitch of a note is determined by the frequency of the 
sound wave. The higher the frequency of a note, the higher 
it's pitch. See Frequency. 
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Pixel: Computer term for picture element. Each dot on the screen 
that makes up an image is called a pixel. Each character on 
the screen is displayed within an 8 X 8 grid of pixels. The 
entire screen is composed of a 320 X 200 pixel grid. In bit- 
map mode, each pixel corresponds to one bit in the 
computer's memory. 


Polling: A communications control method used by some 
computer/terminal systems whereby a ‘master’ station asks 
many devices attached to a common transmission medium, in 
turn, whether they have information to send. 


Pointer: A register used to indicate the address of a location in 
memory. 


Port: A channel! through which data is transferred to and from the 
CPU. An 8-bit CPU can address 256 ports. 


Printer: Peripheral device that outputs onto a sheet of paper. This 
paper is referred to as a hard copy. 


Program: A series of instructions that direct the computer to 
perform a specific task. Programs can be stored on diskette 
or cassette, reside in the computer’s memory, or be listed on 
a printer. 


Programmable: Capable of being processed with computer 
instructions. 


Program Line: A statement or series of statements preceded by a 
line number in a program. The maximum length of a program 
line on the Commodore 128 is 160 characters. 


PROM: Acronym for Programmable Read Only Memory. A 
semiconductor memory whose contents cannot be changed. 


Protocol: The rules under which computers exchange information, 
including the organization of the units of data to be 
transferred. 


Random Access Memory (RAM): The programmable area of the 
computer’s memory that can be read from and written to 
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(changed). All RAM locations are equally accessible at any 
time in any order. The contents of RAM are erased when the 
computer is turned off. 


Random Number: A nine-digit decimal number from 0.000000001 
to 0.999999999 generated by the RaNDom (RND) function. 


Read Only Memory (ROM): The permanent portion of the 
computer's memory. The contents of ROM locations can be 
read, but not changed. The ROM in the Commodore 128 
contains the BASIC language interpreter, character-image 
patterns and portions of the operating system. 


Register: Any memory location in RAM. Each register stores one 
byte. A register can store any value between 0 and 255 in 
binary form. 


Release: The rate at which the volume of a musical note 
decreases from the sustain level to zero. 


Remark: Comments used to document a program. Remarks are 
not executed by the computer, but are displayed in the 
program listing. 


Resolution: The density of pixels on the screen that determine the 
fineness of detail of a displayed image. 


RGBI Monitor: Red/Green/Blue/intensity. A high-resolution 
display device necessary to produce an 80-column screen 
format. 


Ribbon Cable: A group of attached parallel wires. 


Ring Network: A system in which all stations are linked to form a 
continuous loop or circle. 


RS-232: A recommended standard for electronic and mechanical 
specifications of serial transmission ports. The Commodore 
128 parallel user port can be treated as a serial port if 
accessed through software, sometimes with the addition of an 
interface device. 
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Screen: Video display unit which can be either a television or 
video monitor. 


Screen Code: The number assigned to represent a character in 
screen memory. When you type a key on the keyboard, the 
screen code for that character is entered into screen memory 
automatically. You can also display a character by storing its 
screen code directly into screen memory with the POKE 
command. 


Screen Memory: The area of the Commodore 128’s memory that 
contains the information displayed on the video screen. 


Serial Port: A port used for serial transmission of data; bits are 
transmitted one bit after the other over a single wire. 


Serial Transmission: The sending of sequentially ordered data 
bits. 


Software: Computer programs (sets of instructions) stored on disk, 
tape or cartridge that can be loaded into random access 
memory. Software, in essence, tells the computer what to do. 


Sound Interface Device (SID): The MOS 6581 sound synthesizer 
chip responsible for all the audio features of the Commodore 
128. 


Source Code: A non-executable program written in a high-level 
language. A compiler or assembler must translate the Source 
code into an object code (machine language) that the 
computer can understand. 


Sprite: A programmable, movable, high-resolution graphic image. 
Also called a Movable Object Block (MOB). 


Standard Character Mode: The mode the Commodore 128 
operates in when you turn it on and when you write programs. 


Start Bit: A bit or group of bits that identifies the beginning of a 
data word. 


Statement: A BASIC instruction contained in a program line. 
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Stop Bit: A bit or group of bits that identifies the end of a data word 
and defines the space between data words. 


String: An alphanumeric character or series of characters 
surrounded by quotation marks. 


Subroutine: An independent program segment separate from the 
main program that performs a specific task. Subroutines are 
called from the main program with the GOSUB statement and 
must end with a RETURN statement. 


Subscript: A variable or constant that refers to a specific element 
in an array by its position within the array. 


Sustain: The midranged volume of a musical note. 


Synchronous Transmission: Data communications using a 
synchronizing, or clocking, signal between sending and 
receiving devices, 


Syntax: The grammatical rules of a programming language. 
Tone: An audible sound of specific pitch and waveform. 


Transparent: Describes a computer operation that does not 
require user intervention, i.e. the user is unaware that it is 
taking place. 


Variable: A unit of storage representing a changing string or 
numeric value. Variable names can be any length, but only 
the first two characters are stored by the Commodore 128. 
The first character must be a letter. 


Video Interface Controller (VIC): The MOS 6566 chip responsible 
for the 40-column graphics features of the Commodore 128. 


Voice: A sound-producing component inside the SID chip. There 
are three voices within the SID chip so the Commodore 128 
can produce three different sounds simultaneously. Each 
voice consists of a tone oscillator/waveform generator, an 
envelope generator and an amplitude modulator. 
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Waveform: A graphic representation of the shape of a sound 
wave. The waveform determines some of the physical 
Characteristics of the sound. 


Word: Number of bits treated as a single unit by the CPU. In an 


eight-bit machine, the word length is eight bits; in a 16-bit 
machine, the word length is 16 bits. 
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